Authentication

Primicornis supports two first-class authentication modes on the same REST surface:

Interactive (browser)

1. User signs in with Amazon Cognito Hosted UI.
2. Next.js exchanges the authorization code and sets an HTTP-only session cookie for the API (primicornis_id_token).
3. Same-origin requests from app.primicornis.com include that cookie automatically.

Use this path for product UI only — not for long-running scripts.

Automation (API tokens)

1. Workspace admins mint tokens under Settings → Developer.
2. Choose an access level for the token: read only or read and write.
3. Store the prim_* secret in your secret manager; Primicornis persists only a SHA-256 hash with a server-side pepper.
4. Send the token as Authorization: Bearer prim_... on every request.

API tokens are bound to the workspace where they were created. A token minted in workspace A cannot be used against workspace B, even if the creating user belongs to both. Workspace role checks still apply, and if the creating user loses access to that workspace, the token stops authenticating.

Example header

Authorization: Bearer prim_00000000-0000-4000-8000-000000000000_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Never log raw tokens, commit them to git, or paste them into support tickets.

JWT vs token precedence

If a request includes both a Bearer Primicornis token and session cookies, the Bearer Primicornis token wins (prefix prim_). Cognito ID tokens use the standard JWT shape and are verified with AWS’s JWKS.

Rotating credentials

Audit events for mint/revoke are on the roadmap; until then, rely on CloudTrail for AWS-level IAM changes and application logs for API errors.