API Keys

An API key authenticates requests to Hookdeck's APIs. Each key belongs to an organization or a single project, and its scopes define which resources you can read or change.

Manage organization keys and project keys from Organization API Keys. You can also manage the current project's keys from project API key settings.

Create a separate key for each application or integration, and give it only the project access and scopes it needs. Store keys in your application's secret manager and send them in the Authorization: Bearer <your-api-key> header.

Organization API keys

An organization API key can call the Platform API to manage organization details, projects, and project API keys. It can also access resources through the Event Gateway API or Outpost API, depending on the project's type and the key's scopes.

Choose which projects the key can access:

• All projects: Access applies to all projects in the organization, including projects created later.
• Specific projects: Access applies only to the selected projects. The same selected scopes apply to each of them.

See the Outpost scope limitation before relying on these restrictions for Outpost management endpoints.

Project access and scopes work together. For example, a key with gateway.events.read and access to two Event Gateway projects can read events in those projects. It cannot retry events or read events in other projects.

When calling a project's API with an organization key, include the Project-ID header to select the project:

curl "https://api.hookdeck.com/2026-09-01/events" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY" \
  -H "Project-ID: $PROJECT_ID"

Create an organization key

Organization owners and admins can create organization API keys in the dashboard.

1. Visit Organization API Keys.
2. Click New Organization API Key.
3. Enter a name that identifies the application or integration.
4. Choose All projects or Specific projects, then select the projects if needed.
5. Choose the key's scopes.
6. Click Create Organization API Key and copy the key for your application.

Organization API keys cannot use the Platform API to create or manage other organization keys. With api-keys.write, an existing organization key can create, edit, roll, and delete project keys, but cannot grant a project key permissions it does not hold when creating, editing, or rolling it.

Project API keys

A project API key is bound to one project. Use it to access that project's Event Gateway or Outpost resources. It cannot call the Platform API or access another project, even if it has All scopes.

A project key automatically selects its project when authenticating. You do not need to send a project-selection header.

Create a project key

curl -X POST "https://api.hookdeck.com/2026-09-01/organizations/current/api-keys" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Event reader",
    "type": "project",
    "team_id": "tm_123456789",
    "scopes": ["gateway.events.read"]
  }'

Publishing to Outpost's /publish endpoint requires a project API key with outpost.events.write. Organization API keys cannot authenticate to this endpoint.

Scopes

Scopes control the actions a key can perform within its organization and project access. The dashboard offers three options:

• All scopes: Grants all available permissions within the key's access boundaries.
• Read-only: Grants read access to the applicable resources. For organization keys, this excludes api-keys.read, because listing API keys exposes key material.
• Specific scopes: Choose None, Read, or Write for each resource. Attempts and metrics only offer read access.

A scope combines a resource family and an action, such as gateway.sources.read. Write includes read, so gateway.sources.write allows reading, creating, updating, and deleting sources. Actions such as retrying or replaying also require the relevant write scope.

The API also accepts * for all scopes and <family>.* for all actions in a family, such as gateway.sources.*. Wildcards do not expand a key's project access or allow project keys to call the Platform API. A request without its required scope returns 403.

Platform scopes

Platform scopes are available to organization API keys.

organizations.read
organizations.write
projects.read
projects.write
api-keys.read
api-keys.write

The api-keys.read scope lists accessible project API keys, including their secrets. The api-keys.write scope creates, edits, rolls, and deletes project API keys.

Event Gateway scopes

Event Gateway scopes apply to Event Gateway projects.

gateway.connections.read
gateway.connections.write
gateway.sources.read
gateway.sources.write
gateway.destinations.read
gateway.destinations.write
gateway.transformations.read
gateway.transformations.write
gateway.issue-triggers.read
gateway.issue-triggers.write
gateway.bookmarks.read
gateway.bookmarks.write
gateway.issues.read
gateway.issues.write
gateway.events.read
gateway.events.write
gateway.requests.read
gateway.requests.write
gateway.attempts.read
gateway.metrics.read
gateway.publish.read
gateway.publish.write

Publishing requires gateway.publish.write; gateway.publish.read does not authorize publishing. Reading or managing sources alone does not authorize publishing. Replaying a bookmark requires gateway.events.write.

Outpost scopes

The following scope families are available for Outpost projects.

Outpost management endpoints currently do not enforce resource scopes or the specific-project selection on organization keys. Do not rely on these settings to restrict Outpost management access. The /publish endpoint requires a project key with outpost.events.write.

outpost.tenants.read
outpost.tenants.write
outpost.destinations.read
outpost.destinations.write
outpost.events.read
outpost.events.write
outpost.attempts.read
outpost.metrics.read

Edit a key

curl -X PUT "https://api.hookdeck.com/2026-09-01/organizations/current/api-keys/apk_3fVq8tR1nZx0" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": [
      "gateway.events.read",
      "gateway.requests.read"
    ]
  }'

Editing permissions keeps the existing secret. To replace the secret, roll the key.

Roll a key

Rolling creates a replacement key with the same name, project access, and scopes. You choose when the old key expires so you can update your applications before it stops working.

curl -X POST "https://api.hookdeck.com/2026-09-01/organizations/current/api-keys/apk_3fVq8tR1nZx0/roll" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "delay_sec": 3600
  }'

The replacement key works immediately. During a rollover period, both keys authenticate requests. When the period ends, the old key stops working. Choosing now revokes the old key as soon as it is rolled.

A key that already has an expiration time cannot be rolled again. Use the replacement key for future rotations.

Delete a key

curl -X DELETE "https://api.hookdeck.com/2026-09-01/organizations/current/api-keys/apk_3fVq8tR1nZx0" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY"

Deleting permanently revokes the key. Applications using it can no longer authenticate, so update them to use another key before deleting it.