# 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](https://dashboard.hookdeck.com/settings/organization/api-keys). You can also manage the current project's keys from [project API key settings](https://dashboard.hookdeck.com/settings/project/secrets).

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](/docs/platform/api) to manage organization details, projects, and project API keys. It can also access resources through the [Event Gateway API](/docs/api) or [Outpost API](/docs/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](#outpost-scopes) 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:

```bash
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](https://dashboard.hookdeck.com/settings/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](#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

### Dashboard

1. Visit [Organization API Keys](https://dashboard.hookdeck.com/settings/organization/api-keys).
2. In the Project API Keys section, click New API Key.
3. Enter a name and select the project.
4. Choose the key's [scopes](#scopes). The available scopes match the project's product.
5. Click Create Project API Key and copy the key for your application.

You can also manage keys for the current project in [project API key settings](https://dashboard.hookdeck.com/settings/project/secrets).

### API

Use an organization API key with `api-keys.write` to call `POST /organizations/current/api-keys`. The organization key must also hold every scope that you grant to the new key on the target project.

```bash
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"]
  }'

```

The response contains the new secret in `key`. Store it securely when you create it.

> 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.

```text
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.

```text
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`.

```text
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

### Dashboard

From [Organization API Keys](https://dashboard.hookdeck.com/settings/organization/api-keys), open the key's ... menu and click Edit Key. Update its name, scopes, or, for an organization key, project access, then save your changes.

### API

Use an organization API key with `api-keys.write` to update a project key's scopes or resource grants. The API does not update the key's label.

```bash
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.

### Dashboard

1. Open the key's ... menu and click Roll Key.
2. Set Key expiration to now, in 1 hour, or in 24 hours.
3. Click Roll API Key.
4. Copy the replacement key and update every application that uses the old key before the expiration time.

### API

Use an organization API key with `api-keys.write`. Set `delay_sec` to keep the current key valid for `0`, `3600`, or `86400` seconds. The response contains the replacement secret in `key`.

```bash
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

### Dashboard

Open the key's ... menu and click Delete Key, then confirm with Delete.

### API

Use an organization API key with `api-keys.write` to delete a project key:

```bash
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.