API keys
Create a secret key for your server, choose what it may do, scope it to one avatar if you like, and cap what it can spend.
Create a key
- Open Studio → API.
- Click Create API key and give it a name you will recognise later ("marketing site").
- Pick the scopes it needs (below), optionally set caps, and set Avatar access if the key should work with one avatar only.
- Copy the secret. It is shown exactly once. We keep only a hash; if you lose it, rotate the key.
Afterwards the list shows the name, the prefix (sk_atmee_a1b2…), the last four characters, when
the key was last used, and how many visitor minutes it produced this month.
Creating keys requires a plan with API access (the Pro tiers). On other plans the button explains what to upgrade to.
Scopes
A key can only call what its scopes allow; anything else answers 403 insufficient_scope.
| Scope | Allows |
|---|---|
sessions | Start visitor sessions with POST /v1/session. On by default. |
avatars:read | List your avatars and read an avatar's build status. |
avatars:write | Create, update and delete avatars, and replace their image, voice or knowledge. |
billing:write | Move credits into and out of an avatar's sponsor budget. |
Give an integration the smallest set that works: a key that only starts sessions on your site
needs sessions and nothing else.
Caps
| Cap | Meaning | Default |
|---|---|---|
| Max session (minutes) | Hard stop for a single session started with this key. | Your plan's maximum |
| Max concurrent sessions | How many sessions this key may have running at once. | Your plan's maximum |
| Spend cap | Credits this key may spend, over a total, monthly or daily window. | None |
A key can only be more restrictive than your plan — the plan is the real ceiling. When a cap is
hit, /v1/session answers 402 with api_key_spend_cap_reached or concurrent_session_limit.
Account-wide or avatar-scoped
By default a key works with every avatar your account owns, including avatars you create
later; the session request names the avatar with avatarId. If you prefer one key per site or
per avatar, set Avatar access to that avatar — when you create the key, or at any time
afterwards from Edit key. A scoped key gets 403 for any other avatar.
Scoping is not only a session filter. A key scoped to one avatar gives up account-wide access:
| Account-wide key | Scoped key | |
|---|---|---|
| Start a session for its avatar | Yes | Yes |
| Start a session for any other avatar | Yes | 403 |
| Read and update its own avatar | Yes | Yes |
| Fund its own avatar's sponsor budget | Yes | Yes |
| Create, list or delete avatars | Yes | 403 |
Widening a scoped key back to every avatar restores all of it.
Rotate and revoke
- Rotate issues a new secret for the same key (same name, scopes, caps and avatar) and invalidates the old one. Do this if a secret may have leaked.
- Revoke disables the key permanently. Sessions already running continue to their end; new
ones are refused with
401.
Both take effect within about 30 seconds — the API caches key lookups briefly.
Keeping the secret safe
- Store it in your server's environment or secret manager, never in the repository.
- Never put it in page JavaScript, a mobile app, or a public config — anyone who can read it can spend your credits.
- Use one key per integration so a leak is contained and easy to rotate.
Usage
The Active integrations card on the same page shows, per key and per avatar, visitor minutes this month and the last time the key was used. "Not embedded yet" means the key exists but has never started a session.