How do I authenticate in CI or a headless environment?

How do I get a Unison key without clicking an email link every time?

The standard provisioning flow (POST /v1/auth/provision → email OTP → POST /v1/auth/verify) is designed for a human in the loop. For CI and machine contexts you run it once, store the resulting key, and reuse it — the key doesn't expire unless you rotate it.

Steps

1. Provision once from a machine with inbox access.

curl -X POST https://brain.unisonlabs.ai/v1/auth/provision \
  -H 'content-type: application/json' \
  -d '{"email": "ci@yourcompany.com"}'

You'll receive an OTP at that address.

2. Verify the OTP to activate the key.

curl -X POST https://brain.unisonlabs.ai/v1/auth/verify \
  -H 'content-type: application/json' \
  -d '{"email": "ci@yourcompany.com", "code": "123456"}'

The response includes your usk_live_... key.

3. Store it as a secret.

Put the key in your CI secret store (GitHub Actions UNISON_TOKEN, Doppler, AWS Secrets Manager, etc.). Do not commit it to source control.

4. Use it in every request.

curl 'https://brain.unisonlabs.ai/v1/brain/context?q=deployment+decisions' \
  -H "Authorization: Bearer $UNISON_TOKEN"

Tips

Use a dedicated email address for each service (ci-staging@, ci-prod@). That way you can rotate one key without affecting others, and the audit trail is clean.

Keys are long-lived. If you suspect a key was exposed, see Rotating keys.