Authentication

Primatomic uses JWT (JSON Web Tokens) for API authentication. This document specifies the authentication requirements and token lifecycle.

Authentication Requirements

All authenticated endpoints require a valid JWT in the Authorization header. Requests without a valid token receive a 401 Unauthorized response.

curl https://api.primatomic.com/logs \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Authentication Methods

API Keys (Recommended for Services)

API keys are long-lived JWTs minted by POST /keys. The response body’s key field is the JWT itself. Use it directly as the bearer token; there is no separate exchange step.

Create one via the dashboard, or programmatically after logging in as an owner:

curl -X POST https://api.primatomic.com/keys \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-service", "expires_in_days": 365}'

Response:

{
  "api_key_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "production-service",
  "key": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "role": "member",
  "created_at": "2026-04-30T12:00:00Z",
  "expires_at": "2027-04-30T12:00:00Z"
}

Caution

The key value is only returned once. Store it securely immediately. The service will not provide it again.

User Login (For Dashboard Access)

Interactive users authenticate with email and password and receive a short-lived session JWT:

curl -X POST https://api.primatomic.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your_password"
  }'

Login fails with 403 Forbidden if the email address has not been verified.

Token Lifecycle

Token kind	Lifetime	How to renew
API key JWT	expires_in_days at creation; default 365 days	Create a new key and revoke the old one
Session JWT (login)	1 hour (server-configurable)	Log in again

Revocation: when an API key is revoked, the cell that handled the revoke rejects the JWT immediately. Other cells reject it within one cache refresh interval (a few seconds). Expired and revoked tokens both produce 401 Unauthorized.

There is no refresh endpoint. API key JWTs are long-lived by design; rotate by minting a new key, deploying it, then revoking the old one. Session JWTs are short-lived; on 401, send the user through /auth/login again.

API Key Management

Listing API Keys

curl https://api.primatomic.com/keys \
  -H "Authorization: Bearer $TOKEN"

The response contains metadata only. The key value is not retrievable after creation.

Revoking an API Key

curl -X DELETE https://api.primatomic.com/keys/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $TOKEN"

The cell handling the revoke rejects the JWT immediately. Other cells pick up the change within one cache refresh interval. Revocation is irreversible.

Security Requirements

Requirement	Level	Description
Key storage	Required	Treat the JWT as a credential. Store in a secrets manager or environment variable.
Client-side exposure	Prohibited	Do not embed JWTs in browser-side code or commit them to version control.
Key rotation	Recommended	Rotate keys periodically by minting a new one and revoking the old one.
Naming	Recommended	Use descriptive names indicating service or environment.
Expiration	Recommended	Use shorter expires_in_days for short-lived or temporary access.
Monitoring	Recommended	Watch /billing/usage for anomalies.

Error Responses

Status	Condition	Client Action
401	Token missing, expired, or revoked	For services: mint a new API key. For sessions: log in again.
403	Email not verified (login)	Verify email before retry
429	Rate limit exceeded	Respect Retry-After header