HOhookdeck
Organizations

Create an API key

Changed on

Create an organization or project API key. Creating organization API keys requires an admin session. Organization API keys can only create project keys, and only with scopes they hold on that project.

post/organizations/current/api-keys

Request

  • Base URL
    https://api.hookdeck.com/2025-07-01
  • Auth
    • HTTP bearer
    • or HTTP basic

Request body

labelstring required
type'organization' | 'project' required
team_idstring
scopesstring[]

Permission scopes; defaults to ["*"] (full access) when omitted. For organization keys limited to specific projects, these scopes apply within each granted project. When the caller is an API key, every scope (including per-resource grant scopes) must be one the caller itself holds on the target project.

grantsobject

Organization keys: the projects the key is limited to, keyed by project ID with true (or {}) values — scopes stay in the root scopes property. Project keys: per-resource scope overrides keyed by resource ID.

Example request

{
  "label": "CI pipeline",
  "type": "organization",
  "scopes": [
    "gateway.sources.read"
  ]
}

Response

The created API key

idstring required

The API key ID

labelstring required

The API key label

keystring

The API key secret used as the bearer token

team_idstring nullable

The project the key is scoped to, or null for organization keys

organization_idstring

The organization the key belongs to

key_fingerprintstring nullable

Non-secret fingerprint identifying the key

scopesstring[]

Base permission scopes; ["*"] is full access

grantsobject

Per-subject scope overrides: keyed by project ID for organization keys, resource ID for project keys

expires_atstring nullable

When the key expires, or null while active

updated_atstring

Last update timestamp

created_atstring

Creation timestamp

Example response

{
  "id": "apk_3fVq8tR1nZx0",
  "label": "CI pipeline",
  "key": "hd_org_a1b2c3d4e5f6...",
  "organization_id": "org_9bML1qH2vXp3",
  "key_fingerprint": "a1b2c3d4",
  "scopes": [
    "gateway.sources.read",
    "gateway.events.write"
  ],
  "grants": {
    "tm_9bML1qH2vXp3": {
      "scopes": [
        "gateway.events.read"
      ]
    }
  },
  "updated_at": "2025-06-01T12:00:00.000Z",
  "created_at": "2025-01-15T08:30:00.000Z"
}

Changes