API Keys

Purpose

API keys allow SaaS backends to authenticate directly with saas-core for server-to-server operations, such as querying subscription status.

This is separate from user authentication. API keys are scoped to a specific application and grant access only to authorized operations.

Creating Keys

In the admin console, enter a name for the key and create:

POST /api/admin/applications/tobby/api-keys
{ "name": "production", "scopes": ["commerce:read", "users:read"] }

Response (shown once, cannot be retrieved):

{
  "api_key": {
    "id": "ak_xxx",
    "key_prefix": "sak_aBcD...",
    "scopes": ["commerce:read", "users:read"]
  },
  "plaintext": "sak_xxxxx"
}

Using Keys

SaaS backends send the API key in the Authorization header:

GET /api/commerce/status?user_id=u_xxx
Authorization: Bearer sak_xxxxx

saas-core validates the key by:

1. Computing SHA-256 of the provided key
2. Looking up the hash in application_api_key table
3. Checking the key has not expired
4. Verifying the requested operation is within the key’s scopes

Scopes

Scope	Permission
commerce:read	Read subscription and order data
commerce:write	Create checkouts, manage subscriptions
users:read	Read user membership data
users:write	Update user memberships

Security

• Keys are stored as SHA-256 hashes
• The plaintext key is shown only at creation
• Keys can be revoked at any time from the admin console
• Key prefixes are displayed to help identify keys without exposing secrets