API keys

An API key lets your own code and automations message your agent over HTTP. A key is scoped to one agent and acts as you — the agent and the person you act as are fixed by the key. Only you can see or revoke the keys you create.

Creating a key

In the Ayven web app, open your agent's settings and go to API keys, then choose Create key. The form takes three fields:

Field	Required	Meaning
`Label`	required	A name for the key so you can tell them apart later — e.g. `CI pipeline`.
`Rate limit per minute`	optional	How many requests per minute this key may make. Requests over the limit get `429`.
`Expires in days`	optional	Days until the key expires. Leave empty and the key never expires.

The secret is shown once. When the key is created, the plaintext secret appears a single time — copy it then. It cannot be retrieved again afterwards; if you lose it, revoke the key and create a new one.

Using a key

Keys have the form ak_<keyId>_<secret> and are passed as a bearer token on every request:

Authorization: Bearer ak_<keyId>_<secret>

A minimal call — send the agent a message and get her reply:

curl -X POST https://platform-gateway-3124114101.europe-west1.run.app/api/v1/api-channel/messages \
  -H "Authorization: Bearer ak_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "What is the status of the Q3 board update?"
  }'

The full endpoint contract — request fields, response statuses, long-running turns, error codes — is in the API reference.

Key statuses

Each key on the API keys page shows its label, status, rate limit, when it was last used, and when it expires. A key is in one of four states:

Status	Meaning
`active`	The key works. Requests authenticate normally.
`revoked`	The key was revoked. Requests with it get `401`.
`expired`	The key passed its expiry date. Requests with it get `401`.
`inactive`	The key is disabled. Requests with it get `401`.

Revoking a key

On the API keys page, choose Revoke on an active key and confirm. Revocation is permanent — the key is disabled immediately and every request that presents it is refused with 401 from then on. Only the key's creator can revoke it.