HOhookdeck
Organizations

Roll an API key

Changed on

Roll an API key: the current key expires after the rollover delay and a replacement key is returned. Organization API keys can only roll project keys whose scopes they hold on that project.

post/organizations/current/api-keys/{id}/roll

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

delay_sec0 | 3600 | 86400 float required

Seconds the current key stays valid after the roll

Example request

{
  "delay_sec": 3600
}

Response

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