Getting started

Authentication

Creating API keys, sending them with requests and choosing scopes.

View as Markdown

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:

  1. Choose new, give the key a name (and optionally a description).
  2. Select the scopes the key needs.
  3. 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:

text
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:

bash
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.tts AYETO text to speech Text to speech
ayeto.data_loader AYETO file to text Converting a file to text

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.

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.