Authentication

Getting an API Key

API keys are issued by an organization admin via the ZenSpace admin UI. Ask the admin to:

1. Create a key scoped to their organization.

2. Give it a descriptive name (e.g. "Google Calendar bridge — production").

3. Set key_type to live for production or test for sandbox use.

4. Optionally restrict it to specific IPs and set an expiry.

5. Share the plain key out-of-band. The plain value is shown only once at creation time and is SHA-256 hashed at rest.

Keys look like zsk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX or zsk_test_...

Sending the API Key

Send the key on every request via the x-api-key header. The following forms are accepted, in order of preference:

Priority	Header	Example
1 (preferred)	x-api-key	zsk_live_...
2	x-org-api-key	zsk_live_...
3	Authorization	Bearer zsk_live_...

Key Rotation

Rotate the key periodically (90 days is a reasonable default):

1. Ask the admin to issue a new key.

2. Deploy the new key to your bridge.

3. Verify traffic succeeds.

4. Ask the admin to revoke the old key.

Auth Failure Modes

Condition	HTTP	Message
Key not found / hash mismatch	401	Invalid or expired API key
Key revoked (is_active=false)	401	Invalid or expired API key
Key expired (expires_at past)	401	Invalid or expired API key
Request IP not in allowed_ips	401	Invalid or expired API key
No key sent on a key-required route	401	route-specific