API keys

Every API call from your server carries a key. Calls are billed to the account that owns the key, so your users need no Atmee account. Keys start on the Starter plan; the Free plan has no API access.

Authenticate a requestCopy Anchor Link

Send the key in the X-Api-Key header, from your server only. The base URL is https://api.atmanity.us.

To check a key, call GET /v1/api_keys/current with it. It answers with the key's name, scopes, avatar and caps, and under spendCap what it has spent in this window, what's left and when the window resets. It never returns the secret.

curl https://api.atmanity.us/v1/api_keys/current \
  -H "X-Api-Key: $ATMEE_API_KEY"

Keys look like sk_atmee_…. Keys made before September 2026 start with sk_live_… and work the same way.

Create a keyCopy Anchor Link

Only the account's owner or an admin can create, rotate or revoke keys, and only while signed in. A key can never manage keys, so a leaked key can't make more.

Open Studio → API

Click Create API Key.

Name it

Use a name you'll recognise later, such as the app or site it serves.

Choose what it may do

Pick its scopes, set its caps, and choose Avatar access: every avatar, or one avatar only.

Copy the secret

The secret is shown once

Atmee keeps only a hash. If you lose the secret, rotate the key to get a new one.

Afterwards the list shows each key's name, its prefix (sk_atmee_ and 8 more characters), its last four characters, and when it was last used.

From a terminalCopy Anchor Link

The atmee CLI, signed in as the owner or an admin with atmee login, writes the secret straight into your env file and never prints it:

atmee keys create --name "marketing site" \
  --avatar 11111111-2222-4333-8444-555555555555 \
  --spend-cap 50 --out .env

ScopesCopy Anchor Link

Every key can start sessions; the other scopes unlock the rest. A call that needs a scope the key lacks answers 403 insufficient_scope.

Recommended setupsCopy Anchor Link

Give each key the smallest set that works.

CapsCopy Anchor Link

Each key can carry its own limits, so a busy or abused page can't run up an unlimited bill. A key can only be stricter than your plan: a value above your plan's is lowered to it.

The 500-credit default applies to keys created through the API or the CLI without a spend cap. On an unlimited plan the spend cap is not applied (spendCap.enforced: false).

When a cap is hit, the start answers 402 with api_key_spend_cap_reached or concurrent_session_limit. A session asking for more time than the key allows isn't refused: it's cut, and the answer says so in durationCapped.

Visitor memoryCopy Anchor Link

A key can allow visitor memory: the avatar remembers a returning user across sessions. It's off by default. With it on, your server passes a visitorId of at least 16 characters when it starts a session. Whoever can name that id reads that user's conversation history, so derive it on your server (for example an HMAC of your own user id) and never take it from the page.

Account-wide or one avatarCopy Anchor Link

By default a key works with every avatar your account owns, including ones you create later, and the request names the avatar with avatarId. Set Avatar access to one avatar, when you create the key or later from Edit key, and the key works with that avatar only. Other avatars answer 403 avatar_not_allowed.

A key bound to one avatar gives up account-wide access:

Widening the key back to every avatar restores all of it.

Rotate and revokeCopy Anchor Link

• Rotate issues a new secret for the same key. The key keeps its id, name, scopes, avatar and caps, and the old secret stops working. Do this whenever a secret may have leaked. A revoked key can't be rotated (409 api_key_revoked).
• Revoke turns the key off for good. Sessions it already started keep running to their end; new calls answer 401. Revoking twice is no error.

Both take effect within about 30 seconds, because the API caches key lookups briefly. In Studio, both are on the key's menu. From a terminal:

atmee keys rotate <key-id> --out .env   # new secret into .env, the old one stops working
atmee keys revoke <key-id> --yes

Sponsor poolsCopy Anchor Link

A sponsor pool holds credits set aside for one avatar, so visitors on atmee.ai can talk to it on your credits.

Amounts are in microcredits: 100 microcredits are 1 credit. Credits from the Free plan can't fund a pool (402 free_plan_credits_cannot_sponsor).

ErrorsCopy Anchor Link

More in Troubleshooting.

Keep the secret safeCopy Anchor Link

• Server only. Store it in your server's environment or secret manager. A key in page JavaScript can be read by every visitor, and anyone who can read the key can spend your credits.
• Never in a repository, page JavaScript, a mobile app or a public config. Add your .env to .gitignore.
• One key per app, bound to that app's avatar where you can, so a leak is contained and you can rotate it without touching anything else.
• Always set a spend cap on a key behind a public page, and put your start route behind your own sign-in and a rate limit. The cap is the backstop.

UsageCopy Anchor Link

In Studio → API, the key list shows each key's minutes this month and when it was last used, and the cards above it count active integrations and visitor minutes this month. On Manage, "Not embedded yet" marks an avatar no key has started a session with. For a single session's cost, call GET /v1/sessions/{id}.