This guide shows you how to find your Server URL and Authorization Token, create an API key with the permissions you need, test it in the API playground on this site, and delete a key you no longer use. You need all three values before you can call any Ejento AI API.How API keys work#
Every request to the Ejento AI API carries three values. You find all of them on the API Keys page in Organization settings:Server URL: the address of your organization's API server. It's the base URL for every request: put it in front of the endpoint path.
API key (also called a subscription key or secret key): identifies the calling app and decides which APIs it may use. Send it in the Ocp-Apim-Subscription-Key header.
Authorization Token: identifies you. Send it in the Authorization header as a Bearer token: Authorization: Bearer <your token>.
Don't share your API key or Authorization Token with anyone, and never put them in browser or other client-side code.
Use cases#
Reporting dashboard: Create a Read Only key for a dashboard that only reads data. It can call GET endpoints but can't create, change, or delete anything.Single-purpose integration: Create a Restricted key for an integration that manages agents. Give it Write on the agent categories it uses and None on everything else, so a leaked key can't reach the rest of your organization's data.Trying the API: Paste your values into the API playground on this site and send a request before you write any code.
Find your Server URL and Authorization Token#
1. Open Organization settings#
Click your name at the bottom of the sidebar, then click Organization settings.Only admins can open Organization settings, so only admins can create and manage API keys.
2. Open API Keys#
In Organization Settings, click API Keys.3. Copy your Server URL and Authorization Token#
Click the copy icon next to Server URL and save the value: it's the base URL for your requests. Then click the copy icon next to Authorization Token and save it too: send it in the Authorization header as a Bearer token.
Create a new API key#
4. Start a new key#
On the API Keys page, click Create new secret key.5. Name the key and choose its permissions#
In Create New Subscription Key, enter a Key Name (optional, but a name like "Reporting dashboard" helps you find the key later). Under Permissions, choose what the key can do, then click Create Key.| Permission | What the key can do | Choose it when |
|---|
| All | Full read and write access to every API category. | The app needs to read and change data across Ejento AI. |
| Read Only | Can only call GET endpoints, in every category. No write access. | The app only reads data, for example a report or a dashboard. |
| Restricted | Choose the access for each API category separately. | The app works with a few areas only, and you want to keep everything else closed. |
If you choose Restricted, set each API Category in the list:None: no access to the category's endpoints.
Read: only the category's GET endpoints.
Write: all of the category's endpoints (GET, POST, PUT, DELETE, and so on).
6. Copy your secret key#
Click the copy icon to copy the key, save it somewhere safe, then click Done.The secret key is shown only once. If you lose it, create a new key.
7. Find the key in the list#
Your new key appears in the list on the API Keys page, with its permission and status. Use Search API keys... and the Owner and Status filters to find a key in a long list.
Test your key in the API playground#
Try your key on this site before you write code. The playground sends the request with the values you enter.8. Open the API documentation#
On the API Keys page, click API Documentation next to Learn more. This site opens in a new tab.9. Open an endpoint and click Try it#
In the sidebar, choose the endpoint you want to test, then click Try it. The Try it out panel opens on the right.10. Open the server variable#
In the Try it out panel, click the link icon next to the method to open the base URL, then click {{your-server-name}}.11. Enter your values#
In Personal variables, paste your values into the Value column, then click Save & Exit:| Variable | Paste |
|---|
| your-server-name | The Server URL from step 3 |
| your-api-key | The secret key from step 6 |
| your-access-token | The Authorization Token from step 3 |
These values are stored only in your browser. They aren't saved to your account or shared with anyone.
12. Send the request#
Fill in any parameters the endpoint needs, then click Send. The result appears under Response.
Delete an API key#
13. Click the delete icon#
On the API Keys page, click the delete icon in the Actions column of the key you want to remove.14. Revoke the key#
In Revoke Secret Key, click Revoke. The key is disabled right away and removed from the list.After you revoke a key, you can't view or change it again, and requests that use it are rejected. Move any app that still uses the key to a new key first.
