Authentication
AvatarGo has two kinds of credentials, one for each side of your app:
| Who holds it | What it can do | Lasts | |
|---|---|---|---|
API key (ar_sk_…) | Your server | Everything the API offers your account | Until you revoke it |
| Session token | The end user’s browser | Join one session | One hour, one session |
Your server uses the API key to create a session and gets a session token back; it hands only the token to the page. See How a session works.
API keys
Create one in the AvatarGo console : open API Keys and press Create key, with a label that tells you where it is used (say, “production server”). The key is shown once: copy it then. The list afterwards shows each key’s label, its first characters, when it was created and when it was last used.
Send it on every request, in the Authorization header:
curl https://api.avatargo.ai/v1/avatar-models \
-H "Authorization: Bearer $AVATARGO_API_KEY"- Keep it on your server. A key has full access to your account’s API: anyone holding it can create sessions as you. Never put it in a web page, a mobile app or a repository; keep it in an environment variable or your secret store.
- One key per place — your production server, staging, a script — so you can revoke one without touching the others.
- Revoke a key in the console (Revoke on its row) when it is no longer used or may have leaked. It stops working from the next request; the key stays in the list, marked revoked.
- A few things are done only in the console, never with a key, so a leaked key cannot be used for
them: creating and revoking API keys, managing webhook endpoints, and payments — top-ups, plans,
automatic top-up and the saved card. With a key these answer
403 forbidden.
A missing, unknown or revoked key answers 401 unauthorized (it does not say which). An account on hold
answers 403 forbidden.
Session tokens
POST /v1/auth/session-token, called by your server with your API key, creates a session and returns a
sessionToken for it. Give that token to the end user’s page, which joins with it:
createClient(sessionToken) in the JavaScript SDK.
- It is safe to hand to the browser: it names one session only, and carries neither your key nor your character’s settings.
- It is valid for one hour, and only for its session. While the session is live, joining again with
the same token rejoins it; once the session is over, the token is refused (
410 session_ended). - It is accepted only where the browser needs it — joining the session, the avatar’s picture shown while it connects, and ending it. Everything else needs your API key.
- Create a new session, and a new token, for each call.