On this page

API keys

List your organization’s keys and revoke exposed or unused credentials yourself. Revocation takes effect on the key’s next request.

Request new keys through Pricing and access.

:org is your organization's slug or its org_... id. A key can only address its own organization: any other value answers 404, exactly as an organization that does not exist would.

A key has leaked. Do this now.

# 1. find its id
curl -s -H "authorization: Bearer $DOCSARY_KEY" \
  "$DOCSARY_API/v1/orgs/acme/keys"

# 2. kill it
curl -s -X DELETE "$DOCSARY_API/v1/orgs/acme/keys/key_9f2c..." \
  -H "authorization: Bearer $DOCSARY_KEY"

After revocation, update the affected tool with a replacement key. Other keys and published content are unaffected.

If the leaked key is the only key you have, use it to revoke itself — that is allowed however narrow its scopes are. See Revoking the key you are holding.

List keys

GET /v1/orgs/:org/keys

curl -s -H "authorization: Bearer $DOCSARY_KEY" \
  "$DOCSARY_API/v1/orgs/acme/keys"

{
  "org": "acme",
  "keys": [
    {
      "id": "key_9f2c1d0a4b6e8f1c2d0a4b6e8f1c2d0a",
      "name": "ci",
      "scopes": "write",
      "created_at": 1756300000000,
      "last_used_at": 1756399000000,
      "revoked_at": null,
      "revoked": false
    },
    {
      "id": "key_3a7b5c9d1e2f3a7b5c9d1e2f3a7b5c9d",
      "name": "docs-linter",
      "scopes": "read",
      "created_at": 1756200000000,
      "last_used_at": null,
      "revoked_at": 1756350000000,
      "revoked": true
    }
  ]
}

Keys are listed newest first. Read-only keys may list them.

Field	Meaning
`id`	The `key_...` id. This is what you pass to revoke, and it is safe to write down
`name`	The name the key was issued under
`scopes`	`write` or `read` — see Conventions
`created_at`	Millisecond timestamp of issue
`last_used_at`	Millisecond timestamp of the key's most recent request, or `null` if it has never been used
`revoked_at`	Millisecond timestamp of revocation, or `null`
`revoked`	`true` once revoked. A revoked key stays listed

Revoked keys remain listed with their revocation date.

Review last_used_at to identify unexpected activity or potentially unused keys. Confirm a key’s purpose before revoking it; an unused key may be reserved for future work.

What a listing never contains

The response contains neither the token nor its stored hash. A lost key cannot be recovered: revoke it and request a replacement.

Revoke a key

DELETE /v1/orgs/:org/keys/:id

curl -s -X DELETE "$DOCSARY_API/v1/orgs/acme/keys/key_9f2c..." \
  -H "authorization: Bearer $DOCSARY_KEY"

{
  "revoked": true,
  "self": false,
  "key": {
    "id": "key_9f2c1d0a4b6e8f1c2d0a4b6e8f1c2d0a",
    "name": "ci",
    "scopes": "write",
    "created_at": 1756300000000,
    "last_used_at": 1756399000000,
    "revoked_at": 1756400000000,
    "revoked": true
  }
}

Immediate: the revoked key receives 401 on its next request.

Irreversible: a revoked key cannot be restored.

Idempotent: repeating the request returns 200 with already_revoked: true.

Who may revoke

Caller	May revoke
A write-capable key	Any key in its own organization
A read-only key	Only itself

Revoking the key you are holding

Any key may revoke itself, whatever its scopes. If the credential that leaked is the read-only one, and it is the only one you have to hand, you can still stop it:

# whoami tells you which key you are holding
curl -s -H "authorization: Bearer $DOCSARY_KEY" "$DOCSARY_API/v1/whoami"

{ "kind": "org", "org": { "slug": "acme" }, "scopes": "read", "key_id": "key_3a7b..." }

Passing that key_id to the revoke call works, and the response says so:

{
  "revoked": true,
  "self": true,
  "note": "That was the key this request authenticated with. It is dead now."
}

This key cannot authenticate another request after it revokes itself.

Errors

Response	Cause
`401`	No token, or the token has already been revoked
`403` containing `read-only`	A read-only key tried to revoke a different key
`404 {"error":"key not found"}`	No such key id in this organization — including a real key id belonging to somebody else
`404 {"error":"org not found"}`	The `:org` value is not your organization

Other organizations’ resources are not disclosed.

Good practice

Use a separate key for each tool so you can replace one without changing all integrations.
Request read-only access where writing is unnecessary.
Review last-use dates and remove credentials you no longer need.
Revoke an exposed key promptly, then investigate the exposure and update affected tools.

PreviousReports NextBilling