Scopix

Documentation

API Keys Reference

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

API Key Format

API keys follow the format scopix_ followed by an 8-character alphanumeric identifier and a random secure suffix. 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

json
{
  "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

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "api_key": "scopix_Ab12CdEf3g4h5i6j7k8l9m0nOpQrSt...",  // Only returned on creation
  "name": "Production API Key",
  "description": "Key for production application",
  "key_prefix": "scopix_Ab12CdEf",
  "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

json
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production API Key",
      "description": "Key for production application",
      "key_prefix": "scopix_Ab12CdEf",
      "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
    }
  ],
  "summary": {
    "active_count": 1,
    "inactive_count": 0
  },
  "total_count": 1,
  "limit": 50,
  "offset": 0,
  "has_more": false
}
GET/api/v2/api-keys/{api_key_id}

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

Response

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production API Key",
  "description": "Key for production application",
  "key_prefix": "scopix_Ab12CdEf",
  "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 properties (requires ADMIN role)

Request

json
{
  "name": "Updated Production Key",
  "description": "Updated description",
  "scopes": ["read"],
  "metadata": {"environment": "production", "version": "2.0"},
  "rate_limit_override": 120
}


// All fields are optional — only provided fields will be updated
// name: 1-255 chars
// description: max 500 chars
// scopes: replaces existing scopes entirely (cannot exceed your role permissions)
// metadata: merged with existing metadata (not replaced)
// rate_limit_override: custom requests/minute limit (positive integer)
// Note: is_active and expires_at cannot be changed via update

Response

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Updated Production Key",
  "description": "Updated description",
  "key_prefix": "scopix_Ab12CdEf",
  "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"],
  "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.

Request

json
// Optional query parameter:
// ?reason=string    - Reason for revocation, stored in the key's audit metadata

Response

json
// Returns 204 No Content on success

Scopes Reference

Role-Based Scopes (Tenant-Wide)

Grant access to all resource types at the specified permission level.

  • • read - Read-only access to all resources (VIEWER role equivalent)
  • • write - Read/write/delete access to all resources (EDITOR role equivalent)
  • • admin - Full administrative access to all resources (ADMIN role equivalent)

Resource-Specific Scopes

Restrict access to only the named resource. Use these for least-privilege API keys. Format: resource:action where action is read, write, delete, or share.

  • • files:read / files:write / files:delete / files:share - Access to uploaded files (images, documents, videos)
  • • rules:read / rules:write / rules:delete - Access to rules and listings
  • • api_keys:read / api_keys:write - View or manage API keys
  • • analyses:read / analyses:write - View or create analysis results
  • • usage:read - View usage statistics and tenant settings
  • • tenants:read - View tenant information and settings
  • • cloud_storage:read / cloud_storage:write / cloud_storage:delete - Manage cloud storage connections

Resources without a specific scope (e.g., chat, videos, documents) are only accessible via role-based scopes. You can combine multiple granular scopes, e.g., ["rules:read", "analyses:write"].

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. Role-based and resource-specific scopes can be mixed: role-based scopes provide a baseline across all resources, while granular scopes add resource-specific access.

Related

Authentication Guide

Using API keys in requests

Session Auth Reference

Session-based authentication