API Keys Management

The API Keys endpoints allow you to manage your API keys for authentication.

Base URLs

• GET /api/keys - List API keys
• POST /api/keys - Generate new API key
• DELETE /api/keys/{id} - Revoke API key

Authentication

Requires user authentication (session-based, not API key authentication).

List API Keys

Retrieve all active API keys for the authenticated user.

Request

GET /api/keys

Response

{
  "keys": [
    {
      "id": "key_123456789",
      "name": "Production API Key",
      "prefix": "ak-prod-",
      "created_at": "2024-01-01T12:00:00Z",
      "last_used": "2024-01-15T10:30:00Z",
      "usage_count": 1250,
      "status": "active"
    },
    {
      "id": "key_987654321",
      "name": "Development API Key", 
      "prefix": "ak-dev-",
      "created_at": "2024-01-10T09:15:00Z",
      "last_used": "2024-01-16T14:22:00Z",
      "usage_count": 45,
      "status": "active"
    }
  ],
  "total": 2
}

Generate New API Key

Create a new API key for your account.

Request

POST /api/keys
Content-Type: application/json

{
  "name": "My New API Key",
  "description": "API key for my new project"
}

Parameters

Response

{
  "id": "key_abc123def456",
  "name": "My New API Key",
  "description": "API key for my new project",
  "key": "ak-proj-1234567890abcdef1234567890abcdef",
  "prefix": "ak-proj-",
  "created_at": "2024-01-16T15:30:00Z",
  "status": "active"
}

Important: The full API key is only shown once during creation. Store it securely as it cannot be retrieved again.

Revoke API Key

Permanently revoke an API key, making it invalid for future requests.

Request

DELETE /api/keys/{id}

Parameters

Response

{
  "success": true,
  "message": "API key revoked successfully",
  "id": "key_abc123def456"
}

Error Responses

Key Not Found

{
  "error": {
    "message": "API key not found",
    "type": "not_found_error",
    "code": "key_not_found"
  }
}

Unauthorized

{
  "error": {
    "message": "Authentication required",
    "type": "authentication_error", 
    "code": "unauthorized"
  }
}

Invalid Request

{
  "error": {
    "message": "Missing required parameter: 'name'",
    "type": "invalid_request_error",
    "code": "missing_required_parameter"
  }
}

Usage Examples

List Keys (JavaScript)

const response = await fetch('/api/keys', {
  method: 'GET',
  credentials: 'include', // Include session cookies
});

const data = await response.json();
console.log('API Keys:', data.keys);

Generate New Key (JavaScript)

const response = await fetch('/api/keys', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include',
  body: JSON.stringify({
    name: 'Production API Key',
    description: 'Key for production environment'
  })
});

const data = await response.json();
console.log('New API Key:', data.key);
// Store this key securely - it won't be shown again!

Revoke Key (JavaScript)

const keyId = 'key_abc123def456';
const response = await fetch(`/api/keys/${keyId}`, {
  method: 'DELETE',
  credentials: 'include',
});

const data = await response.json();
console.log('Key revoked:', data.success);

Using cURL

List Keys

curl -X GET https://your-domain.com/api/keys \
  -H "Cookie: your-session-cookie"

Generate Key

curl -X POST https://your-domain.com/api/keys \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "name": "My API Key",
    "description": "For my application"
  }'

Revoke Key

curl -X DELETE https://your-domain.com/api/keys/key_abc123def456 \
  -H "Cookie: your-session-cookie"

Security Considerations

1. Store keys securely: Never expose API keys in client-side code or public repositories
2. Use environment variables: Store keys in environment variables in production
3. Rotate keys regularly: Generate new keys periodically and revoke old ones
4. Monitor usage: Check the usage_count and last_used fields to monitor key activity
5. Use descriptive names: Give keys meaningful names to track their purpose
6. Revoke unused keys: Remove keys that are no longer needed

Rate Limits

Key management operations are rate limited:

• List keys: 100 requests per minute
• Generate key: 10 requests per minute
• Revoke key: 50 requests per minute

Best Practices

1. One key per environment: Use separate keys for development, staging, and production
2. One key per application: Don't share keys between different applications
3. Document key purposes: Use the description field to document what each key is used for
4. Regular audits: Periodically review your active keys and revoke unused ones
5. Monitor for suspicious activity: Check the usage patterns of your keys regularly