Authentication

DID.comms uses a dual-layer authentication model: a session Bearer token for user identity, and an X-DID-API-Key header for sovereign identity selection.

Authentication Model

Layer 1 — Session Token

Authorization: Bearer <your_session_token>

Authenticates you as a user. Required on all endpoints except /ping and /v1/did/activate.

Layer 2 — API Key Header

X-DID-API-Key: ak_your_api_key_here

Selects which sovereign identity to act as. Each API key maps to a unique did:comms: identity. If omitted, the api_key_id can be passed in the request body as a fallback.

API Key Lifecycle

activeKey is ready to send and receive envelopes.

revokedKey has been permanently deactivated. Returns 403 KEY_INACTIVE.

rotatingKey is mid-rotation. Temporarily paused.

deactivatedKey has been administratively disabled.

Key Rotation

There is no key rotation endpoint. The canonical flow is:

1.Revoke the compromised key from the dashboard

2.Generate a new key via /v1/did/activate

3.Update your webhook registrations with the new api_key_id

4.Update your application to use the new key

NOTE: Revoking a key is permanent. The associated did:comms: identity remains on record but can no longer send or receive envelopes.

Check Identity Status

curl -X POST https://arcform-api.com/v1/did/status \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-DID-API-Key: ak_YOUR_KEY"