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 token in the Authorization header. Requests without a valid token receive a 401 Unauthorized response.

Authentication Methods

API Key Exchange (Recommended for Services)

Services and automated clients should use API key exchange. POST the API key to obtain a JWT:

curl -X POST https://api.primatomic.com/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "pk_live_abc123..."}'

The service responds with:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

User Login (For Dashboard Access)

Interactive users can authenticate with email and password:

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 Usage

Include the token in the Authorization header using the Bearer scheme:

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

Token Lifecycle

Property	Specification
Lifetime	Tokens expire after 3600 seconds (1 hour)
Renewal	Obtain a new token before expiry
Revocation	Tokens associated with revoked API keys are rejected

Token Refresh

Implement automatic token refresh:

1. On receiving 401 Unauthorized, request a new token
2. Refresh tokens proactively before expiry
3. Do not cache tokens beyond their expiry time

API Key Management

Creating an API Key

Authenticated clients can create additional API keys:

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

The service responds with the plaintext key:

{
  "api_key_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "production-service",
  "key": "pk_live_abc123...",
  "created_at": "2024-01-19T12:00:00Z"
}

Caution

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

Key Expiration (Optional)

Specify an expiration period:

curl -X POST https://api.primatomic.com/keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "temp-key", "expires_in_days": 30}'

Keys with expiration automatically become invalid after the specified period.

Listing API Keys

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

The response does not include plaintext key values.

Revoking an API Key

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

Revoked keys immediately cease to function. Tokens previously issued for revoked keys are rejected.

Security Requirements

Requirement	Level	Description
Key Storage	Required	API keys should be stored securely (e.g., secrets manager, environment variables)
Client-Side Exposure	Prohibited	API keys should not be exposed in client-side code or version control
Key Rotation	Recommended	Keys should be rotated periodically
Naming	Recommended	Keys should use descriptive names indicating service/environment
Expiration	Recommended	Temporary access should use keys with expiration
Monitoring	Recommended	Usage should be monitored via /billing/usage for anomalies

Error Responses

Status	Condition	Client Action
401	Invalid, expired, or revoked token/key	Obtain a new token
403	Email not verified (login)	Verify email before retry
429	Rate limit exceeded	Respect Retry-After header