API Keys

An API key is an Organization-owned machine credential. It is not a personal access token: once issued, its authority is independent of the person who created it, so a Role change or a departure neither widens nor narrows the integration.

• Prefix

  ulsav_sk_

• Scope

  Exactly one

  It covers that subtree's descendants

• Secret

  Shown once

  Later reads return the prefix only

• Authority

  Frozen at issue

  Independent of the creator

• Managed by

  A session, never a key

• Expiry

  Optional

  High-risk keys should carry one

Create a keyCopy Anchor Link

Create keys in the organizer webapp under Settings → API Keys, or call the operation below with a signed-in session.

Every action requires a session-authenticated human, and an API key can never manage another.

A creation request carries:

POST /api/v1/organizations/{organization_id}/api-keys
Content-Type: application/json

{
  "name": "Order sync",
  "capabilities": ["orders.read", "registrations.read"],
  "scopeType": "Organization",
  "expiresAt": "2027-11-06T00:00:00Z",
  "allowedOrigins": ["https://app.example.com"]
}

The response contains the key metadata and the secret, shown exactly once:

{
  "apiKey": {
    "id": "019ae4b0-...",
    "name": "Order sync",
    "prefix": "ulsav_sk_...",
    "capabilities": ["orders.read", "registrations.read"],
    "scopeType": "Organization",
    "status": "active"
  },
  "secret": "ulsav_sk_..."
}

The apiKey object also carries organizationId, scopeId, allowedOrigins, createdAt, and updatedAt. Store the secret in your secret manager before leaving the page. Later reads return metadata and the prefix only; there is no "show secret again" operation.

What the key can doCopy Anchor Link

Authority is fixed at issuance and is deliberately narrow:

• It is a subset of the issuer. Selected capabilities and Scope must fit inside the creating member's effective authority at that Scope.
• It does not follow the issuer. If the creator later loses a Role or leaves the Organization, the key keeps its frozen authority until a member with api_keys.create or api_keys.revoke in the Organization acts on it.
• It has exactly one Scope. That Scope covers its descendants through the resource hierarchy, so a key scoped to an EventGroup can act on that group's Events, but not on a sibling Event.
• It is allowed per operation. Key access is a default-deny decision made operation by operation. An endpoint used by the browser session is not automatically available to keys.

An operation that does not declare API-key policy rejects a key with 403 api_key_forbidden, even if the key names a similarly named capability. An operation that does declare policy checks three things in order:

1. The Organization in the path must equal the key's Organization.
2. The capability must match exactly.
3. The key's Scope must be the target or one of its ancestors.

Failures are 403 api_key_forbidden or 403 api_key_scope_denied.

What a key can never doCopy Anchor Link

The api_keys.* capability family is human-only and is never valid on a key. A key cannot create, list, read, edit, roll, or revoke any key, including itself. This is enforced at the HTTP layer as well as at issuance, so an operation mistakenly configured to accept keys for key management still rejects them.

Organization suspension or platform suspension overrides every key: requests fail with organization_suspended or platform_suspended until the suspension is lifted.

Rotate and revokeCopy Anchor Link

POST /api/v1/organizations/{organization_id}/api-keys/{api_key_id}/roll

Rolling and revoking answer different questions:

Unlike webhook signing secrets, a roll has no grace window, so schedule the cutover and restart workers that cache the old value. Revoke rather than delete.

POST /api/v1/organizations/{organization_id}/api-keys/{api_key_id}/revoke

A revoked key and an expired key both fail authentication with 401; their statuses read revoked and expired.

QuestionsCopy Anchor Link