API Key Usage and Integration Recipes | AuthOS Docs | Auth Operating System API and SDK Guides

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.

Permission Enforcement

Each endpoint checks for required permissions:

// Error when lacking permissions
{
  "error": "Insufficient permissions. Required: write:users",
  "error_code": "FORBIDDEN",
  "timestamp": "2025-01-15T10:30:00Z"
}

Key Expiration

Expired keys are rejected with an error:

{
  "error": "API key has expired",
  "error_code": "UNAUTHORIZED",
  "timestamp": "2025-01-15T10:30:00Z"
}

Examples

Create Read-Only Analytics Key

curl -X POST https://sso.example.com/api/organizations/acme-corp/services/main-app/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytics Dashboard (Read-Only)",
    "permissions": ["read:analytics", "read:service"]
  }'

Create Full-Access Backend Key

curl -X POST https://sso.example.com/api/organizations/acme-corp/services/main-app/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Server (Full Access)",
    "permissions": [
      "read:users",
      "write:users",
      "read:subscriptions",
      "write:subscriptions",
      "read:analytics"
    ]
  }'

Create Temporary CI/CD Key

curl -X POST https://sso.example.com/api/organizations/acme-corp/services/main-app/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline - Sprint 42",
    "permissions": ["read:users", "read:subscriptions"],
    "expires_in_days": 30
  }'

Node.js Service Integration

const SSO_API_KEY = process.env.SSO_API_KEY;
const SSO_API_BASE = 'https://sso.example.com';

async function getUserSubscription(userId) {
  const response = await fetch(
    `${SSO_API_BASE}/api/service/subscriptions/${userId}`,
    {
      headers: {
        'X-Api-Key': SSO_API_KEY
      }
    }
  );

  if (!response.ok) {
    throw new Error(`AuthOS API error: ${response.status}`);
  }

  return response.json();
}

// Usage
const subscription = await getUserSubscription('user-uuid');
console.log(`User plan: ${subscription.plan_name}`);

Python Service Integration

import os
import requests

SSO_API_KEY = os.environ['SSO_API_KEY']
SSO_API_BASE = 'https://sso.example.com'

def get_user_subscription(user_id):
    response = requests.get(
        f'{SSO_API_BASE}/api/service/subscriptions/{user_id}',
        headers={'X-Api-Key': SSO_API_KEY}
    )
    response.raise_for_status()
    return response.json()

# Usage
subscription = get_user_subscription('user-uuid')
print(f"User plan: {subscription['plan_name']}")