Authentication

FractalPack supports two authentication methods: API keys (recommended for server-to-server) and JWT Bearer tokens (for browser-based apps using Cognito).

API Keys

Creating a key

curl -X POST https://api.fractalpack.com/api/v1/keys \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "warehouse-integration",
    "expiresInDays": 90
  }'

Response:

{
  "keyId": "key_8f3a2b1c",
  "apiKey": "fpk_live_abc123def456...",
  "keyPrefix": "fpk_live_abc",
  "label": "warehouse-integration",
  "isActive": true,
  "mode": "live",
  "createdAt": "2026-04-03T12:00:00Z",
  "expiresAt": "2026-07-02T12:00:00Z"
}

The full key value is only returned once at creation. Store it securely.

Test vs live keys

Prefix	Environment	Purpose
`fpk_test_`	Sandbox	Development and testing. No production data access.
`fpk_live_`	Production	Live organization data. Use in production systems only.

Using an API key

Pass the key in the X-Api-Key header on every request:

curl https://api.fractalpack.com/api/v1/items \
  -H "X-Api-Key: fpk_live_abc123def456..."

The API key authenticates the request and binds it to your organization. No additional org ID header is needed -- the key carries the org context.

Listing keys

curl https://api.fractalpack.com/api/v1/keys \
  -H "Authorization: Bearer <your_jwt_token>"

Returns all active keys for your organization. The full key value is not included -- only the key ID, label, and metadata.

Revoking a key

curl -X DELETE https://api.fractalpack.com/api/v1/keys/key_8f3a2b1c \
  -H "Authorization: Bearer <your_jwt_token>"

Returns 204 No Content on success. The revoked key is immediately invalid -- any in-flight requests using it will receive 401 Unauthorized.

JWT Bearer Tokens

For browser-based applications, authenticate with a JWT from your Cognito user pool:

curl https://api.fractalpack.com/api/v1/items \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

JWT authentication requires a valid token issued by your organization's configured Cognito user pool. The token must include a valid aud or client_id claim matching your app client ID.

Authentication errors

Status	Meaning
`401 Unauthorized`	Missing, expired, or invalid API key / JWT token
`403 Forbidden`	Valid credentials, but the user or key lacks permission for this operation

Example 401 response:

{
  "type": "https://developers.fractalpack.com/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or revoked API key.",
  "instance": "0HN8ABC123"
}

Security best practices

Never expose keys in client-side code. API keys are server-side secrets. Use a backend proxy for browser apps.
Use test keys in development. Switch to fpk_live_ only in production environments.
Rotate keys regularly. Set expiresInDays when creating keys and replace them before expiry.
Revoke compromised keys immediately. Revocation takes effect instantly.
Use environment variables. Store keys in FRACTALPACK_API_KEY or your secrets manager -- never commit them to source control.
Scope keys to purpose. Create separate keys for each integration (e.g., one for your WMS, one for your ERP) so you can revoke individually.