Authentication and Access

Every Public API request is verified before Deck returns data. Deck does not just check that a key exists. It also checks whether the organization allows API access and whether the key owner is still allowed to use the API.

Access model

Each successful request depends on four things:

1. a valid API key
2. Public API being enabled for the organization
3. the key owner’s current role being allowed
4. the requested scope being enabled

API keys

Deck API keys are:

• created in Settings → API Access
• owned by a specific user
• scoped to a specific organization
• evaluated against endpoint-required scope (read or write)

How requests are authorized

For every authenticated endpoint, Deck performs these checks:

1. extract the API key from the request headers
2. verify the key
3. resolve the key’s organization and owner
4. load the organization’s Public API settings
5. require Public API to be enabled for that organization
6. verify the owner still belongs to that organization
7. verify the owner’s current role is allowed
8. verify the endpoint’s required scope is enabled

If any of those checks fail, the request is rejected immediately.

Scope model

• read scope is used by all read endpoints (GET /themes, GET /insights, etc.)
• write scope is required by Build mutation endpoints:
  • POST /build/initiatives
  • POST /build/opportunities

Write endpoints additionally require an Idempotency-Key header.

Organization policy

Go to Settings → API Access to control who can use the Public API.

Organization admins can:

• enable or disable Public API access
• choose which org roles can use it

Supported roles today:

• admins
• members

By default:

• Public API is disabled
• only admins are allowed

Key ownership

Key ownership matters because access is evaluated against the owner’s current permissions, not just the state at the moment the key was created.

This means:

• if a user loses access, their key stops working
• if a user leaves the organization, their key is revoked
• org members can only manage their own keys in the UI
• org admins can see and revoke all keys for the organization

Headers

Preferred:

Authorization: Bearer dk_us_...

Supported fallback:

X-API-Key: dk_us_...

Error responses

All error responses use the same shape:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or expired API key."
  }
}

Common access errors

Tenant isolation

The Public API is organization-scoped by design:

• the organization is resolved from the verified key
• clients never send an orgId
• all reads are filtered to the authenticated organization

This protects against accidental cross-org access and keeps integrations simple for clients.

Subthemes access

The /subthemes endpoints have one extra rule: the organization must also be eligible for the subthemes feature. If not, those requests return 403 API_DISABLED even if the Public API is otherwise enabled.

Related pages

• Public API
• Resource Reference
• Examples