Skip to main content
POST
/
api-keys
cURL
curl --request POST \
  --url https://api.useanima.sh/v1/api-keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "scopes": [],
  "name": "<string>",
  "mode": "LIVE",
  "agentId": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z"
}
'
{
  "id": "<string>",
  "orgId": "<string>",
  "agentId": "<string>",
  "name": "<string>",
  "prefix": "<string>",
  "scopes": [
    "<string>"
  ],
  "revoked": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "lastUsedAt": "2023-11-07T05:31:56Z",
  "expiresAt": "2023-11-07T05:31:56Z",
  "createdBy": "<string>",
  "key": "<string>",
  "extension": {}
}

Authorizations

​
Authorization
string
header
required

JWT Bearer token obtained from authentication. Pass as: Authorization: Bearer

Body

application/json

Request body for creating a new API key

​
scopes
enum<string>[]
required

Permission scopes granted to this key. Use ['*'] for full access, or list specific scopes from the catalogue (e.g. ['email:read', 'email:send']). An empty array is rejected — empty no longer means 'full access'.

Minimum array length: 1

A single permission scope, or the wildcard '*' for full access

Available options:
*,
email:read,
email:send,
phone:read,
phone:sms,
phone:voice,
phone:provision,
messages:read,
messages:send,
messages:search,
voice:read,
vault:read,
vault:write,
vault:share,
vault:oauth,
identity:read,
identity:write,
agents:read,
agents:write,
inbox:read,
inbox:write,
domains:read,
domains:write,
addresses:read,
addresses:write,
pods:read,
pods:write,
webhooks:read,
webhooks:write,
billing:read,
audit:read
​
name
string

Human-readable label for the API key

Required string length: 1 - 100
​
mode
enum<string>
default:LIVE

Environment mode for the key

Available options:
LIVE,
TEST
​
agentId
string

Restrict this key to a specific agent by ID

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
​
expiresAt
string<date-time>

ISO 8601 timestamp when the key automatically expires

Response

200 - application/json

OK

API key resource including the secret value, returned only on creation

​
id
string
required

Unique identifier for the API key

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
​
orgId
string
required

Organization that owns this API key

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
​
agentId
string | null
required

Agent this key is restricted to, null if unrestricted

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
​
name
string | null
required

Human-readable label for the API key

​
prefix
string
required

Non-secret prefix of the key for identification

​
mode
enum<string>
required

Environment mode of the key

Available options:
LIVE,
TEST
​
scopes
string[]
required

Permission scopes granted to this key

​
revoked
boolean
required

Whether the key has been revoked

​
createdAt
string<date-time>
required

ISO 8601 timestamp when the key was created

​
lastUsedAt
string<date-time> | null
required

ISO 8601 timestamp when the key was last used, null if never used

​
expiresAt
string<date-time> | null
required

ISO 8601 timestamp when the key expires, null if no expiration

​
createdBy
string | null
required

User ID of the key creator, null if created by system

​
key
string
required

Full secret API key value, only returned once at creation time

​
extension
object | null

Extension-token settings surfaced from metadata. Present only for extension:bridge keys.