Aıon

Documentation

API Keys Reference

Create, manage, and rotate API keys with fine-grained scopes

API Key Format

API keys follow the format: aion_... followed by a random string. The full key is only shown once at creation time.

Session Authentication Required

All API key management endpoints require active session authentication. Create, update, and delete operations require ADMIN role. List and detail operations require any authenticated user within the tenant.

Key Management

POST/api/v2/api-keys

Create a new API key (requires ADMIN role). Returns 201 Created.

Request

{
  "name": "Production API Key",
  "description": "Key for production application",
  "scopes": ["read", "write"],
  "metadata": {"environment": "production", "team": "backend"},
  "expires_at": "2026-07-01T00:00:00Z"
}


// Parameters:
// - name: 1-255 chars (required)
// - description: Optional, max 500 chars
// - scopes: Optional array - if empty, inherits creator's permissions
// - metadata: Optional key-value pairs for tracking
// - expires_at: Optional ISO 8601 expiration date (must be in the future). If not set, key never expires.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "api_key": "aion_live_1234567890abcdef...",  // Only returned on creation
  "name": "Production API Key",
  "description": "Key for production application",
  "key_prefix": "aion_live_1234",
  "created_at": "2025-01-15T10:30:00Z",
  "expires_at": "2026-07-01T00:00:00Z",       // null if no expiration set
  "is_active": true,
  "scopes": ["read", "write"],
  "metadata": {"environment": "production", "team": "backend"}
}
GET/api/v2/api-keys

List all API keys for the tenant (requires VIEW permission)

Response

{
  "api_keys": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production API Key",
      "description": "Key for production application",
      "key_prefix": "aion_live_1234",
      "created_at": "2025-01-15T10:30:00Z",
      "last_used_at": "2025-01-15T09:00:00Z",
      "expires_at": "2026-07-01T00:00:00Z",
      "is_active": true,
      "scopes": ["read", "write"],
      "metadata": {"environment": "production", "team": "backend"},
      "usage_count": 142
    }
  ],
  "total": 1
}
GET/api/v2/api-keys/{api_key_id}

Get detailed information about a specific API key (requires VIEW permission)

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production API Key",
  "description": "Key for production application",
  "key_prefix": "aion_live_1234",
  "created_at": "2025-01-15T10:30:00Z",
  "last_used_at": "2025-01-15T09:00:00Z",
  "expires_at": "2026-07-01T00:00:00Z",
  "is_active": true,
  "scopes": ["read", "write"],
  "metadata": {"environment": "production", "team": "backend"},
  "usage_count": 142
}
PUT/api/v2/api-keys/{api_key_id}

Update API key name, description, or metadata (requires ADMIN role)

Request

{
  "name": "Updated Production Key",
  "description": "Updated description",
  "metadata": {"environment": "production", "version": "2.0"}
}


// All fields are optional - only provided fields will be updated
// Note: scopes, is_active, and expires_at cannot be changed via update

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Updated Production Key",
  "description": "Updated description",
  "key_prefix": "aion_live_1234",
  "created_at": "2025-01-15T10:30:00Z",
  "last_used_at": "2025-01-15T09:00:00Z",
  "expires_at": "2026-07-01T00:00:00Z",
  "is_active": true,
  "scopes": ["read", "write"],
  "metadata": {"environment": "production", "version": "2.0"},
  "usage_count": 142
}
DELETE/api/v2/api-keys/{api_key_id}

Revoke an API key (requires ADMIN role). Keys are deactivated, not physically deleted.

Response

// Returns 204 No Content on success

Scopes Reference

Role-Based Scopes

  • • read - Read-only access (VIEWER role equivalent)
  • • write - Read/write access (EDITOR role equivalent)
  • • admin - Administrative access (ADMIN role equivalent)

Resource-Specific Scopes

  • • rules:read - Read access to rules
  • • rules:write - Write access to rules
  • • rules:delete - Delete access to rules
  • • api_keys:read - View API keys
  • • api_keys:write - Manage API keys
  • • usage:read - View usage statistics
  • • verifications:read - View verification results
  • • verifications:write - Create verifications
  • • tenants:read - View tenant information

Scope Validation

If no scopes are specified when creating an API key, it inherits the creator's permissions (capped at admin level). Invalid scopes will be rejected with a 400 Bad Request error.

Related

Authentication Guide

Using API keys in requests

Session Auth Reference

Session-based authentication