Platform API Reference

Use the Platform API to read and update organization details, manage projects, and manage project API keys.

Authentication

Platform endpoints authenticate with an organization-scoped API key — a key created at the organization level rather than inside a single project. Create one in your organization API key settings, then pass it as a bearer token on every request.

An organization key is not limited to the Platform API. It can also call the Event Gateway API and Outpost API for projects it can access. Include the Project-ID header with either project API to select the project.

Access depends on the key's project grants and scopes. See API Keys for project access, available scopes, and key rotation.

Example authenticated request

cURL

curl "https://api.hookdeck.com/2026-09-01/projects"
  -H "Content-Type: application/json"
  -H "Authorization: Bearer $ORGANIZATION_API_KEY"

Organizations

An organization is the top-level entity that owns projects, members, and subscriptions.

Example organization object

JSON

{
  "id": "org_9bML1qH2vXp3",
  "name": "Acme Inc",
  "slug": "acme-inc",
  "domains": [
    "acme.com"
  ],
  "sandbox": false,
  "mfa_required": false,
  "feature_flags": {},
  "sso_enabled": false,
  "directory_sync_enabled": false,
  "updated_at": "2025-06-01T12:00:00.000Z",
  "created_at": "2025-01-15T08:30:00.000Z"
}

Get the current organization

GET

/organizations/current

Request

Shell

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

Response

JSON

{
  "id": "org_9bML1qH2vXp3",
  "name": "Acme Inc",
  "slug": "acme-inc",
  "domains": [
    "acme.com"
  ],
  "sandbox": false,
  "mfa_required": false,
  "feature_flags": {},
  "sso_enabled": false,
  "directory_sync_enabled": false,
  "updated_at": "2025-06-01T12:00:00.000Z",
  "created_at": "2025-01-15T08:30:00.000Z"
}

Update the current organization

PUT

/organizations/current

Request

Shell

curl -X PUT \
  "https://api.hookdeck.com/2026-09-01/organizations/current" \
  -H "Authorization: Bearer $ORGANIZATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Inc"
}'

Response

JSON

{
  "id": "org_9bML1qH2vXp3",
  "name": "Acme Inc",
  "slug": "acme-inc",
  "domains": [
    "acme.com"
  ],
  "sandbox": false,
  "mfa_required": false,
  "feature_flags": {},
  "sso_enabled": false,
  "directory_sync_enabled": false,
  "updated_at": "2025-06-01T12:00:00.000Z",
  "created_at": "2025-01-15T08:30:00.000Z"
}

List API keys

List the active organization and project API keys of the current organization.

GET

/organizations/current/api-keys

Request

Shell

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

Response

JSON

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

Create an API key

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

Shell

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": "CI pipeline",
  "type": "organization",
  "scopes": [
    "gateway.sources.read"
  ],
  "grants": {}
}'

Response

JSON

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

Roll an API key

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.