API keys

API keys let a script, CI job, or external tool work with an organization’s data without a person signing in. A key is owned by the organization, carries its own scopes, and can optionally be limited to one product.

Managing keys requires admin or owner. Create them in the Ablebase app under Settings → API keys.

Scopes

Every key carries one or more scopes. Choose the narrowest set that does the job.

Scope	What it allows
read	GET requests to the organization’s /v1 endpoints.
write	Everything else on /v1: create, update, archive, delete. Implies read.
ingest	Posting reports to POST /api/ingest/test-activity.

write is the one scope that grants another: select it and the key gets read too. Nothing else overlaps, so a key with only ingest can’t read organization data, and a key with read and write can’t post to the ingest endpoint.

How a key is authorized

A key has no role of its own. Its scopes say what it may attempt, never what it’s entitled to, so they can’t grant anything the person who created it can’t already do. Ablebase checks three things on every request:

1. The key’s organization. A key only works against the organization it was created in.
2. The key’s scopes. A read key attempting a write gets 403 Forbidden.
3. The role of the member who created it. The key can never do more than that person can. A key created by a member can’t reach admin-only endpoints, whatever its scopes say.

Because a key borrows its creator’s membership, it stops working when that person leaves the organization. Create keys for shared automation from an account that’s staying, and expect to replace a key when its owner is offboarded.

Caution

Treat a key like a password. Store it in a secret manager or CI secret, never in source control, and revoke it as soon as you suspect it’s been exposed.

Using a key

Send the key as a bearer token:

GET /v1/organizations/:orgId/products
Authorization: Bearer abk_xxxxxxxx

The X-API-Key header works too, which suits tools that reserve Authorization for something else:

GET /v1/organizations/:orgId/products
X-API-Key: abk_xxxxxxxx

Keys start with abk_. A bearer token without that prefix is treated as a session token instead, so the two authentication styles never collide.

Product-scoped keys

A key scoped to a single product may only call endpoints that name that product in the path. Organization-wide endpoints have no product in their path, so a product-scoped key can’t reach them, and returns 403 Forbidden.

List API keys

GET /v1/organizations/:orgId/api-keys

Required role: Admin or owner.

Returns all live (non-revoked) keys, without secrets.

{
  "apiKeys": [
    {
      "id": "...",
      "name": "CI scanner",
      "displayPrefix": "abk_ab12cd",
      "scopes": ["read", "write"],
      "productId": null,
      "productName": null,
      "productSlug": null,
      "ownerUserId": "...",
      "ownerName": "Jane Smith",
      "ownerEmail": "jane@example.com",
      "lastUsedAt": "2025-06-01T00:00:00.000Z",
      "createdAt": "2025-05-01T00:00:00.000Z"
    }
  ]
}

displayPrefix is the non-secret start of the key, enough to tell keys apart in the UI. ownerName and ownerEmail identify the member whose permissions the key borrows.

Create an API key

POST /v1/organizations/:orgId/api-keys

Required role: Admin or owner.

Request body:

Field	Type	Description
name	string	Required (max 120 characters).
scopes	string[]	Required. One or more of read, write, ingest. Requesting write grants read as well.
productSlug	string	Optional. Limits the key to a single product. Omit for a key that covers the whole organization.

Returns 201 Created. The response’s apiKey.key is the plaintext secret. It’s returned only on creation and can’t be retrieved again, so copy it straight into wherever it belongs.

Revoke an API key

DELETE /v1/organizations/:orgId/api-keys/:keyId

Required role: Admin or owner.

Stops the key working immediately. Returns 204 No Content, or 404 Not Found if the key doesn’t exist or was already revoked. Data the key already created stays where it is.

Keys have no expiry date. A key works until you revoke it, or until the member who created it leaves the organization.

Errors

Status	When
401 Unauthorized	The key is missing, malformed, or revoked.
403 Forbidden	The key is valid but not allowed: wrong organization, missing scope, wrong product, or its owner’s role is too low.

A scope failure is deliberately a 403 rather than a 401, so a caller can tell “this key isn’t allowed to do that” from “this key doesn’t work”.

Keys created before scopes existed

Keys minted before this feature shipped were ingest-only credentials. They keep working against the ingest endpoint and appear in the list with the ingest scope and no owner. They can’t call /v1. To use one for API access, create a replacement with the scopes you need and revoke the old key.