Every request to the API is authenticated with an API key. A key belongs to the user who created it: requests made with it act as that user, see what that user can see and spend that user's (or their organization's) credits.
API keys
Create keys in the AYETO app under Profile → API keys:
- Choose new, give the key a name (and optionally a description).
- Select the scopes the key needs.
- Copy the key from the confirmation dialog. The full key is shown only once; afterwards the app shows just its beginning and end so you can recognise it.
A key looks like this:
ayeto-1f0c2b7e9a4d4c6f8e3b5a7d9c1e2f40a8b6c4d2e0f1a3b5c7d9e1f2a4b6c8d0
Keys do not expire. To revoke a key, delete it in the same place; requests with a deleted key fail immediately.
Treat a key like a password: keep it on your server or in a secret store, never in source control or in code that runs in someone else's browser.
Sending the key
Send the key in the uni-api-key header of every request:
curl -X POST "https://ayeto.ai/api/v3/conversation/find" \
-H "uni-api-key: $AYETO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"limit_from": 0, "limit_to": 5}'
No other authentication (cookies, bearer tokens) is needed or accepted by the endpoints in this documentation.
Scopes
A scope allows a key to call a group of endpoints. Give each key only the scopes it
needs. A key with all scopes (*) can call every endpoint.
| Scope | Shown in the app as | Allows |
|---|---|---|
* |
all scopes | Every endpoint, including those that require a scope not listed below. |
ayeto.chat |
AYETO chat | Chat |
ayeto.conversation |
AYETO conversations | Conversations |
ayeto.assistant |
AYETO assistants | Listing assistants and their avatars |
ayeto.workflow |
AYETO workflows (read and run) | Reading and running workflows, runs, approvals |
ayeto.workflow.write |
AYETO workflows (edit) | Creating, editing, publishing, importing and deleting workflows |
ayeto.booster.database |
AYETO booster database (read) | Reading booster database records |
ayeto.booster.database.write |
AYETO booster database (write) | Creating, updating and deleting records, locks |
ayeto.booster.storage |
AYETO booster file storage (read) | Listing booster panel files, download links |
ayeto.booster.storage.write |
AYETO booster file storage (write) | Uploading, moving and deleting panel files |
ayeto.tts |
AYETO text to speech | Text to speech |
ayeto.data_loader |
AYETO file to text | Converting a file to text |
ayeto.embeddings |
AYETO embeddings | Embeddings |
An endpoint that requires several scopes needs all of them on the key. Endpoints that list "any API key" as their scope accept every valid key. Each endpoint's summary table names the scope it requires.
The app also offers the AYETO connectors scope (ayeto.connector). It is used by the
AYETO desktop clients when they pair with your account and is not needed for this API.
A key created by pairing a desktop client has only this scope and cannot call the
endpoints above.
Booster panels acting for a signed-in person
A booster panel with user accounts can let people sign in with their AYETO account. When the panel owner allows it, the panel may then call this API as that person: the sign-in screen lists what the panel asks for (scopes from the table above, or all of them) and the person agrees by signing in.
- The panel sends the session token it received at sign-in (it starts with
bpu_) in theuni-api-keyheader, exactly like an API key. No other header is needed. - The request runs as the person's account with the agreed scopes, never more than the panel asks for at the moment. Each endpoint uses the organizations, assistants and workflows the account can use, as with the account's own API key, and spends the account's credits.
- Endpoints that accept any API key accept such a token too.
- Signing out of the panel, ending the session, losing the right to sign in to the panel (e.g.
leaving its organization) or a narrower setting of the panel ends the access within a minute;
the token is then answered like an invalid key (
401). - Sessions of panel accounts that signed in with a password or an e-mail code never get API access.
Authentication errors
| Status | detail |
Cause |
|---|---|---|
422 |
request validation error naming uni-api-key |
The uni-api-key header is missing. |
401 |
API key not provided |
The uni-api-key header is empty. |
401 |
API key is invalid |
The key does not exist, was deleted or disabled, or lacks a scope the endpoint requires. |
A missing scope is reported the same way as an unknown key, so that a response never
reveals whether a key exists. Failed authentication is answered after a short
deliberate delay; do not retry a 401 in a loop, fix the key or its scopes instead.