Authentication And Key Management

API Key Calls

Send Phase-A API keys as bearer tokens:

Authorization: Bearer vyg_live_xxx

The edge gateway resolves the key through control-plane and identity, then forwards a signed X-Voyage-Session to participating domain workers. Raw Authorization and X-API-Key headers are stripped before forwarding for API-client actors.

Key Format

vyg_live_{8-char-prefix}_{secret}
vyg_test_{8-char-prefix}_{secret}

Only the prefix is stored in readable form. Identity stores a salted SHA-256 hash of the full secret.

Scopes

Scope	Use
`journey.read`	Reserved for read-only journey access; current admin journey routes still require `journey.build`
`journey.build`	List, create, read, update, and publish admin journey surfaces
`registration.write`	Server-side public registration capture workflows

Create A Client And Key

Identity admin APIs require a live identity session cookie for a tenant owner/admin or platform admin.

curl -sS \
  -X POST "https://identity.example.com/t/acme-events/admin/api-clients" \
  -H "content-type: application/json" \
  -H "cookie: identity_session=..." \
  --data '{"name":"Agent builder","description":"Journey automation"}'

curl -sS \
  -X POST "https://identity.example.com/t/acme-events/admin/api-clients/client_xxx/keys" \
  -H "content-type: application/json" \
  -H "cookie: identity_session=..." \
  --data '{"scopes":["journey.build","registration.write"]}'

The mint response returns secret once. Store it immediately in a secret manager.

Rotate Or Revoke

Rotate when a key may have been exposed or when moving to a new key schedule:

curl -sS \
  -X POST "https://identity.example.com/t/acme-events/admin/api-clients/client_xxx/keys/key_xxx/rotate" \
  -H "content-type: application/json" \
  -H "cookie: identity_session=..." \
  --data '{"scopes":["journey.build","registration.write"]}'

Revoke when an integration is retired:

curl -sS \
  -X POST "https://identity.example.com/t/acme-events/admin/api-clients/client_xxx/keys/key_xxx/revoke" \
  -H "cookie: identity_session=..."

Storage Rules

Store keys only in server-side secret managers.
Do not send keys to public browser bundles.
Do not log keys. Log key prefixes only when necessary.
Use separate clients for separate agents so audit and rate-limit records are attributable.