An agent reaches an entity with one of two credentials: an OAuth access token, issued when you sign in from a client, or an entity key (ent_) that you create and paste. Both give full read and write access to that one entity's tools. The portal and REST API also use workspace and user keys.
#Credential types
| Credential | Prefix | Scope | Created by | Lifetime |
|---|---|---|---|---|
| OAuth access token | none | One entity | Signing in from Claude Code, Claude Desktop, claude.ai, ChatGPT, Codex, or another OAuth client | 30 days, renewed with a refresh token |
| Entity key | ent_ |
One entity | You, on the Connect page; the CLI; OAuth sign-in | No expiry, except keys created by OAuth (90 days) |
| Workspace key | fam_ |
One workspace | Pairing a device | No expiry |
| User key | usr_ |
Your account | The desktop app sign-in; the REST API | Optional expiry |
Every key is shown in full once, when it is created. Animawake stores only an HMAC-SHA256 hash and the first 12 characters, which the portal shows so you can tell keys apart. See Security.
#OAuth access tokens
When a client connects with OAuth, you sign in to Animawake and click Allow Access. The client receives an access token that lasts 30 days and a refresh token. A client that supports refresh tokens uses it to get a new access token without asking you to sign in. Each refresh replaces both tokens, and the old ones stop working. A connection can be refreshed until its OAuth (<your email>) key expires, 90 days after the last sign-in or refresh; after that, the client asks you to sign in again.
Each OAuth sign-in also creates an entity key named OAuth (<your email>) that expires after 90 days. The server uses it behind the scenes for that connection, and each refresh replaces it with a new key. You see these keys in the entity's API keys list.
#See connected apps
The entity's Connect page lists OAuth connections under Connected apps, below the setup instructions, with the time each was last used. A connection made with the pre-registered Claude Desktop credentials shows as Claude Desktop. Other clients show the name they registered with, such as Claude Code or ChatGPT.
#Disconnect an app
On the Connect page, choose Disconnect next to the app under Connected apps. The app must sign in again to reconnect.
Disconnecting takes effect at once. It also deactivates the connection's OAuth (<email>) key, and the API checks keys on every request, so the connection's next tool call fails even on an MCP server that still has the token cached.
#Revoke all access
For a lost device or a leaked key, Revoke all access at the bottom of the Connect page deletes every OAuth token and every API key for the entity. It calls DELETE /api/families/<workspace>/entities/<entity>/revoke-all/, which you can also call yourself as a member of the workspace. After that, every agent, the CLI, and every device using the entity must be reconnected.
#Entity keys
Use an entity key when a client cannot complete OAuth: Cursor, scripts, CI, headless servers, or the CLI's stdio bridge.
#Create a key
- Open the entity and go to Connect.
- Under API keys, click Create key and give the key a descriptive name, such as "Cursor on work laptop".
- Copy the key immediately. The portal cannot show it again.
The CLI creates keys for you: npx animawake setup and npx animawake add create a key named "Claude Code CLI". Creating an entity also creates one default key.
The REST API equivalent is POST /api/families/<workspace>/entities/<entity>/api-keys/ with a body such as {"name": "CI runner"}. The response contains the key once. See the REST API overview.
#Use a key
Send it as a bearer token:
Authorization: Bearer ent_your_key_hereOther header names, such as X-API-Key, are not accepted, and keys in query strings are never accepted.
#Revoke a key
On the Connect page, choose Revoke next to the key under API keys. Revoking deletes the key. Deletion is permanent and takes effect within about a minute: the MCP server caches a validated key for up to 60 seconds.
#Rotate a key
In the portal, rotate a key by hand:
- Create a new key.
- Update every place that uses the old key.
- Revoke the old key.
The REST API rotates a key in one step: POST /api/entity-key/rotate/, sent with the key being rotated as the bearer token, returns a new key with the same name and expiry and deactivates the old key at the same moment.
For a CLI project, npx animawake rotate-key <entity-slug> uses that endpoint with the key in .animawake.json and writes the new key back. If the stored key is already deleted or expired, it signs in through the browser instead and writes the new key it receives.
#Workspace keys
A workspace key (fam_) is issued when you pair a device through the portal. The desktop app stores it and uses it for workspace-level work such as heartbeats. You do not need to handle it yourself.
Deleting a device from the portal deactivates the entity keys issued to that device. Keys of the same entities used by the CLI, Cursor, OAuth connections, or other devices keep working. See Devices and the desktop app.
#User keys
A user key (usr_) acts as you, across all of your workspaces. The desktop app receives one when you sign in with Google. You can manage user keys through the REST API at /api/user-api-keys/, including POST /api/user-api-keys/<id>/revoke/.
Signing out of the portal revokes all of your user keys, which also signs the desktop app out on every device.
#Good practice
- Prefer OAuth for interactive clients. Tokens expire on their own and are tied to your sign-in.
- Create one entity key per machine or integration, and name it after where it lives.
- Never commit keys. The CLI adds
.animawake.jsonto.gitignore; keep.cursor/mcp.jsonand similar files out of version control when they contain keys. - Review Connected apps and API keys from time to time and remove what you no longer use.