POST/organizations/{organizationId}/api-keys

Create an API key

Creates a scoped service API key and returns its secret exactly once.

Send request

Use the documented inputs to call this endpoint directly.

API serverbase URL

Bearer tokenBearerAuthoptional

Stored only in this browser for the BearerAuth security scheme and reused on every API page in this group.

Parameters

Values are applied to the request and the example on the right.

organizationIdpath · stringrequired

Opaque organization identifier.

Idempotency-Keyheader · string · uuidoptional

Unique key for retry-safe writes, retained for 24 hours.

Request body

application/jsonrequired

namestringrequired

scopesarray<string>required

expires_atstring · date-timeoptional

project_idsarray<string>optional

Responses

201application/json

API key created.

{
  "id": "key_01J8FF6Q2N4T8P9V3M5",
  "name": "Production data sync",
  "prefix": "heyo_live_",
  "scopes": [
    "contacts:write",
    "exports:read",
    "webhooks:write"
  ],
  "project_ids": [
    "prj_01J8F5KM4MAB0V7YQ6P3N2R8D1"
  ],
  "status": "active",
  "last_used_at": "2026-09-03T11:45:00Z",
  "expires_at": "2027-09-03T00:00:00Z",
  "created_at": "2026-09-01T09:00:00Z",
  "secret": "heyo_live_demo_01J8FF6Q2N4T8P9V3M5"
}

422

Scopes or expiry date are invalid.

curl --request POST \ 'https://api.demo.heyo.example/v3/organizations/org_01J8F1Q6N6VTX4E8W9R2D0A7B3/api-keys' \ --header 'Idempotency-Key: 5ba89923-8c6d-44a3-9ab7-2fbbdb865f9a' \ --header 'Content-Type: application/json' \ --data '{ "name": "Production data sync", "scopes": [ "contacts:write", "exports:read", "webhooks:write" ], "expires_at": "2027-09-03T00:00:00Z", "project_ids": [ "prj_01J8F5KM4MAB0V7YQ6P3N2R8D1" ]}'

{ "id": "key_01J8FF6Q2N4T8P9V3M5", "name": "Production data sync", "prefix": "heyo_live_", "scopes": [ "contacts:write", "exports:read", "webhooks:write" ], "project_ids": [ "prj_01J8F5KM4MAB0V7YQ6P3N2R8D1" ], "status": "active", "last_used_at": "2026-09-03T11:45:00Z", "expires_at": "2027-09-03T00:00:00Z", "created_at": "2026-09-01T09:00:00Z", "secret": "heyo_live_demo_01J8FF6Q2N4T8P9V3M5" }