API keys

An API key lets a script or an agent call the management API on behalf of your organisation. Keys look like sdhk_sk_..., belong to an organisation, and are sent as a bearer token:

curl -s "$API/v1/billing/plan" \
  -H "authorization: Bearer $SDHK_KEY"

Each key is limited to 600 requests per minute.

Agents should prefer Agent Auth where a capability covers what they need. It gives the agent its own identity that a human approves, instead of a shared key.

Create a keyCopy Anchor Link

Keys are created by a person in the dashboard.

1. Open Organization, then API Keys, and click New Key.
2. Give the key a name.
3. Choose Project access: all projects, or exactly one. This cannot be changed later.
4. Set an expiry, or turn expiry off for a key that never expires.
5. Grant permissions per resource, then click Create Key.
6. Copy the key on the next step.

The plaintext key is shown once. If you lose it, revoke the key and create a new one. There is no way to show it again.

Project accessCopy Anchor Link

A key with access to all projects can target any project in the organisation, using the X-Project-Id header. A key bound to one project sees only that project. A request for any other project returns 404, and the key cannot create projects.

PermissionsCopy Anchor Link

Each resource gets one of three levels:

The resources are Projects, Sources, Destinations, Connections, Connectors, Deliveries, Events and Billing. Grant the least access the key needs. A key must hold at least one resource.

Minting a scoped key is capped at your own role in the organisation, so only an owner or admin can create a key with write access to billing.

Unscoped keysCopy Anchor Link

A key with no permissions set, for example one created before scoping existed, is unscoped. It gets the same access as an organisation member: full read, and non-destructive writes (create, update, toggle, retry and replay).

These need an explicit read and write grant on that resource, so an unscoped key cannot do them:

• DELETE on sources, destinations, connections, projects and connectors
• POST /v1/sources/{id}/rotate-mask
• GET /v1/destinations/{id}/signing-secret
• POST /v1/destinations/{id}/rotate-signing-secret
• POST /v1/connectors, and its regenerate-enrollment and toggle-disabled
• the billing mutations: cancel, resume, change-plan and revert-scheduled-change

Rescope a keyCopy Anchor Link

You can change a key's permissions in place from the dashboard. The secret does not change, so nothing using the key needs updating, and the new permissions apply on the next request.

Saving an unscoped key replaces its member-tier fallback with exactly the permissions you choose. The project binding is fixed for the life of the key.

Revoke a keyCopy Anchor Link

Revoking a key is permanent, and any request using it stops working immediately. Use it when a key leaks or is no longer needed. An expired key stops working in the same way.

ErrorsCopy Anchor Link

A 403 INSUFFICIENT_API_KEY_PERMISSIONS will not go away on retry. Ask whoever holds the key to scope it for that resource. It differs from a plain 403 FORBIDDEN, which is a session or organisation refusal, not a key-scope one. A 404 on a resource you expect can mean the key is bound to a different project.

Next stepsCopy Anchor Link

• Agent Auth — the preferred credential for agents
• Projects — how project access works
• Errors — every error code
• Rate limits — the 600 requests per minute limit