AGNTDocs

Authentication

API keys

Create, list and revoke API keys, and check which account, organization or user a key acts for. A new key is shown once.

GET/me

Retrieve the calling key

Returns the account, organization, user and scopes the API key acts for. Use it to check a key before you make other calls.

Responses

200Key context
okboolean
accountIdstring
emailstring | nullThe key's user, for a user-scoped key.
orgIdstring | nullSet for an organization-scoped key.
userIdstring | nullSet for a user-scoped key.
scopesstring[]
401Unknown, revoked or expired API key.

Request

curl 'https://api.agnt.ai/me' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "accountId": "6660c4a1f2e3b7d8a9c01234",
  "email": "[email protected]",
  "orgId": "6660c4a1f2e3b7d8a9c01234"
}
GET/api-keys

List API keys

Returns API keys on your account, newest first, with only the prefix of each key. With `X-User-Email`, returns only that user's keys. `resource=organization` requires an organization admin.

Query parameters

pageinteger
perPageintegerDefault 20, max 100
resourcestringOrganization admin view
scopestringWith resource=organization: user lists per-user keys; otherwise organization-level keys

Responses

200Keys
okboolean
apiKeysobject[]
id reqstring
account reqstring
organizationstring | null
userstring | null
label reqstring
prefix reqstring
scopes reqstring[]
status reqstring
lastUsedAtstring | null
expiresAtstring | null
createdAt reqstring
pageinteger
perPageinteger
totalinteger
403resource=organization without organization admin role

Request

curl 'https://api.agnt.ai/api-keys' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "apiKeys": [
    {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "account": "account",
      "label": "label",
      "prefix": "prefix",
      "scopes": [
        "scope"
      ],
      "status": "status"
    }
  ],
  "page": 1,
  "perPage": 20
}
POST/api-keys

Create an API key

Creates an API key and returns its full value once, in `apiKey.key`. Without `userId`, an account key creates an account-wide key; with `userId`, the new key acts as that user. Creating a key for another user requires an organization admin.

Request body

label reqstringName for the key
userIdstringUser the key acts as. Omit for an account-wide key (organization-scoped when an organization admin creates it)
scopesstring[]Stored with the key; empty means no restriction
expiresAtstring

Responses

201Created
okboolean
apiKeyobject
id reqstringKey id
accountstring
organizationstring | nullSet for an organization-scoped key
userstring | nullThe user the key acts as; null for an account-wide key
labelstring
prefix reqstringThe first characters of the key, shown in lists
scopesstring[]
statusenumactiverevoked
lastUsedAtstring | null
expiresAtstring | null
createdAtstring
key reqstringThe full key (ak_live_...). Returned only in this response and never again: only a hash is stored. Store it now.
400label missing
403Not allowed to create this kind of key
404User or organization not in your account
428The X-User-Email user has not finished setup

Request

curl 'https://api.agnt.ai/api-keys' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "label": "label"
}'

Response

{
  "ok": true,
  "apiKey": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "key": "ak_live_…",
    "prefix": "prefix"
  }
}
POST/api-keys/{keyId}/revoke

Revoke an API key

Disables an API key immediately. A user can revoke their own keys; revoking another user's key requires an admin of the key's organization or an account key.

Path parameters

keyId reqstring

Responses

200Revoked key
okboolean
apiKeyobject
id reqstring
account reqstring
organizationstring | null
userstring | null
label reqstring
prefix reqstring
scopes reqstring[]
status reqstring
lastUsedAtstring | null
expiresAtstring | null
createdAt reqstring
400Already revoked
403Organization admin role required
404API key not found

Request

curl 'https://api.agnt.ai/api-keys/<keyId>/revoke' \
  -X POST \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "apiKey": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "account": "account",
    "label": "label",
    "prefix": "prefix",
    "scopes": [
      "scope"
    ],
    "status": "status"
  }
}
DELETE/api-keys/{keyId}

Delete an API key

Permanently deletes a revoked API key. Revoke the key first. Requires the same permission as revoking it.

Path parameters

keyId reqstring

Responses

200Deleted
okboolean
400The key is not revoked, or is the live key of a deployed app
403Organization admin role required
404API key not found

Request

curl 'https://api.agnt.ai/api-keys/<keyId>' \
  -X DELETE \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true
}