API Key Management on AuthOS Docs | Auth Operating System API and SDK Guides

API Key Endpoint Reference

Mon, 01 Jan 0001 00:00:00 +0000

Data Models

API Key Model

{
  "id": "uuid",
  "service_id": "uuid",
  "name": "Production Backend Server",
  "prefix": "sk_a1b2c3",
  "key_hash": "sha256-hash",
  "permissions": ["read:users", "read:subscriptions", "read:analytics"],
  "last_used_at": "datetime",
  "expires_at": "datetime",
  "created_at": "datetime",
  "created_by": "uuid"
}

API Key Response (without key)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "service_id": "service-uuid",
  "name": "Production Backend Server",
  "prefix": "sk_a1b2c3",
  "permissions": ["read:users", "read:subscriptions", "read:analytics"],
  "last_used_at": "2025-01-20T14:22:00Z",
  "expires_at": "2025-04-15T10:30:00Z",
  "created_at": "2025-01-15T10:30:00Z",
  "created_by": "user-uuid"
}

API Key Create Response (with full key)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "service_id": "service-uuid",
  "name": "Production Backend Server",
  "prefix": "sk_a1b2c3",
  "permissions": ["read:users", "read:subscriptions", "read:analytics"],
  "expires_at": "2025-04-15T10:30:00Z",
  "created_at": "2025-01-15T10:30:00Z",
  "created_by": "user-uuid",
  "key": "sk_a1b2c3_d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"
}

Valid Permissions

API keys support the following granular permissions:

Permission	Description
`read:users`	List and retrieve user information for users who have authenticated with the service
`write:users`	Create and manage users
`delete:users`	Delete users
`read:subscriptions`	List and retrieve subscription information
`write:subscriptions`	Create and update subscriptions
`delete:subscriptions`	Delete subscriptions
`read:analytics`	Access service analytics and metrics
`read:service`	View service configuration
`write:service`	Modify service configuration

Permission Best Practices:

API Key Usage and Integration Recipes

Mon, 01 Jan 0001 00:00:00 +0000

Using API Keys

Authentication

API keys authenticate via the X-Api-Key header:

curl -X GET https://sso.example.com/api/service/users \
  -H "X-Api-Key: sk_a1b2c3_d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"

Available Endpoints

API keys can access service-scoped endpoints under /api/service/*:

GET /api/service/users - List users (requires read:users)
GET /api/service/users/:user_id - Get user details (requires read:users)
POST /api/service/users - Create user (requires write:users)
PATCH /api/service/users/:user_id - Update user (requires write:users)
GET /api/service/subscriptions - List subscriptions (requires read:subscriptions)
GET /api/service/subscriptions/:user_id - Get user subscription (requires read:subscriptions)
POST /api/service/subscriptions - Create subscription (requires write:subscriptions)
PATCH /api/service/subscriptions/:user_id - Update subscription (requires write:subscriptions)
GET /api/service/analytics - Get analytics (requires read:analytics)
GET /api/service/info - Get service info (requires read:service)
PATCH /api/service/info - Update service (requires write:service)

See the Service API Reference for detailed endpoint documentation.

API Key Security and Operations

Mon, 01 Jan 0001 00:00:00 +0000

Security Considerations

Key Format:

Format: sk_{prefix}_{random_component}
Prefix is stored for identification (e.g., sk_a1b2c3)
Random component is 64 characters (high entropy)
Total length: ~74 characters

Storage Security:

Keys are hashed using SHA256 before storage
Verification is intended to use constant-time comparison to reduce timing leakage
The implementation is intended not to store or log the original key; verify redaction in the deployed release
Key shown only once during creation

Permission Model:

API Key Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Begin with the status and error_code. Record only the key prefix when correlating a failure; never paste the full key into tickets, chat, logs, or shell history.

Symptom guide

Symptom	Check	Resolution
Key is rejected immediately	Exact `X-Api-Key` header, copied value, and key existence	Load the credential from the secret manager and avoid whitespace or truncation
A previously valid key returns 401	Expiration and whether the key was deleted or rotated	Deploy the current key or create a replacement with the intended expiry
Request returns 403	Required endpoint permission and key permission list	Create a least-privilege replacement with the required permission
Organization-management route rejects the key	Route family	Use a bearer JWT for organization management; keys are for `/api/service/*`
Key works for the wrong intended workload	Service/environment association	Revoke it and issue separate scoped keys per workload and environment
Response returns 429	Rate-limit headers and request loop	Honor reset/retry guidance, bound concurrency, and eliminate uncontrolled polling
`last_used_at` does not change	Whether the request reached AuthOS with this key	Check proxy routing and credential selection, then make a harmless authorized request
New key was lost after creation	One-time reveal behavior	Delete the unusable key and create a replacement; the plaintext cannot be retrieved

Safe rotation check

Create a replacement with the same required permissions and a deliberate expiry.
Store it directly in the target secret manager.
Deploy and verify a harmless service API read.
Monitor failures and last_used_at.
Delete the old key only after every consumer has moved.

For generic response parsing and retry rules, see API error handling.