HOhookdeck
Organizations

Update an API key

Changed on

Update the scopes and grants of an API key. The secret is unchanged.

put/organizations/current/api-keys/{id}

Request

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

Path parameters

idstring required

API key ID

Request body

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

{
  "scopes": [
    "gateway.sources.read"
  ]
}

Response

The updated 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