Authentication

Authentication

The Aurion API uses API key authentication. Include your key in the X-API-Key header with every request.

curl -H "X-API-Key: itsm_sk_live_xxxx" \
  https://apps.aurionai.net/api/v1/tickets

API keys are formatted as itsm_sk_{env}_{random}. Production keys use the itsm_sk_live_ prefix; sandbox/staging keys use itsm_sk_test_.

API Key Scopes

Each API key is assigned one or more scopes that control which endpoints it can access. Scopes are free-form at creation time — the API lowercases and de-duplicates whatever strings you supply but does not validate them against a catalog. However, only the {resource}:{read|write} pairs derived from the path-prefix allowlist below are ever enforced. Creating a key with an arbitrary scope string succeeds, but that scope is never matched against any endpoint.

The users scope maps to /api/v1/requesters and /api/v1/tenant/users — not /api/v1/users (dashboard user management), which is denied to API keys entirely (see Denied Paths).

Scope Enforcement

Scopes are enforced using path-prefix matching. A key with tickets:read can access any GET/HEAD request under /api/v1/tickets/.

The required action is derived from the HTTP method: GET and HEAD require the :read scope; POST, PUT, PATCH, and DELETE require the :write scope on the matching path prefix. A key holding * satisfies any scope check.

Denied Paths

The following path prefixes are never accessible via API keys regardless of scopes — a request authenticated with X-API-Key returns 403 {"detail": "API keys are not permitted for this endpoint"}:

• /api/v1/api-keys — API key management (use a dashboard session JWT)
• /api/v1/auth — Authentication
• /api/v1/users — Dashboard user management
• /api/v1/tenants — Tenant management
• /api/v1/super-admin — Platform administration
• /api/internal — Internal service endpoints

In addition, any path that is not in the scope allowlist above is rejected with 403 — this includes every /api/v2/* endpoint. API keys can only reach the /api/v1 prefixes listed in the scope table.

Error Responses

Authentication and authorization errors follow the standard error shape — a JSON body with a single detail string. Branch on the HTTP status code and the detail message; there is no error/message envelope.

401 Unauthorized — Invalid API key. The response carries a WWW-Authenticate: Bearer header:

{
  "detail": "Invalid API key"
}

When no credentials are supplied at all, the body is instead:

{
  "detail": "Missing authentication credentials"
}

403 Forbidden — Valid key but insufficient scope:

{
  "detail": "API key missing required scope: tickets:write"
}

403 Forbidden — Valid key but the path is denied to API keys (see Denied Paths):

{
  "detail": "API keys are not permitted for this endpoint"
}

End-User Authentication

End-user endpoints (mobile app, voice widget) use JWT Bearer tokens instead of API keys:

curl -H "Authorization: Bearer eyJhbGciOi..." \
  https://apps.aurionai.net/api/v1/app/tickets

End-user tokens are issued via SSO, password login, or magic link. See the End-User API guide for full authentication details.

API Key Management

Manage API keys programmatically under /api/v1/api-keys. These endpoints require a dashboard session JWT with the tenant_admin role (or higher).

⚠️ Key-management endpoints reject API keys

The /api/v1/api-keys endpoints are in the deny list — a request authenticated with X-API-Key returns 403 {"detail": "API keys are not permitted for this endpoint"}. Authenticate these calls with a dashboard session JWT (Authorization: Bearer <dashboard-jwt>), not an API key.

Create API Key

The request body fields:

curl -X POST "https://apps.aurionai.net/api/v1/api-keys" \
  -H "Authorization: Bearer <dashboard-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "description": "Key for automated deployments",
    "scopes": ["tickets:read", "tickets:write"],
    "expires_in_days": 365
  }'

Response (201 Created):

{
  "id": "key_abc123",
  "name": "CI/CD Pipeline",
  "description": "Key for automated deployments",
  "key_prefix": "a1b2c3d4e5f6",
  "scopes": ["tickets:read", "tickets:write"],
  "created_at": "2026-04-09T00:00:00Z",
  "expires_at": "2027-04-09T00:00:00Z",
  "api_key": "itsm_sk_live_xxxx"
}

The full api_key value is returned only once at creation time. Store it securely. The key_prefix is the first 12 characters of the key's random segment — it identifies the key in listings but is not the full secret.

List API Keys

curl "https://apps.aurionai.net/api/v1/api-keys" \
  -H "Authorization: Bearer <dashboard-jwt>"

Response:

{
  "api_keys": [
    {
      "id": "key_abc123",
      "name": "CI/CD Pipeline",
      "description": "Key for automated deployments",
      "key_prefix": "a1b2c3d4e5f6",
      "scopes": ["tickets:read", "tickets:write"],
      "created_by": "user_xyz",
      "created_at": "2026-04-09T00:00:00Z",
      "expires_at": "2027-04-09T00:00:00Z",
      "last_used_at": "2026-04-10T12:30:00Z",
      "revoked_at": null,
      "is_active": true
    }
  ]
}

The full secret is never returned in listings — only the key_prefix.

Rotate API Key

Generate a new key with the same scopes, revoking the old one:

curl -X POST "https://apps.aurionai.net/api/v1/api-keys/key_abc123/rotate" \
  -H "Authorization: Bearer <dashboard-jwt>"

Response:

{
  "id": "key_def456",
  "key_prefix": "f6e5d4c3b2a1",
  "scopes": ["tickets:read", "tickets:write"],
  "api_key": "itsm_sk_live_rotated_xxxx"
}

Revoke API Key

Immediately deactivate a key without deleting it:

curl -X POST "https://apps.aurionai.net/api/v1/api-keys/key_abc123/revoke" \
  -H "Authorization: Bearer <dashboard-jwt>"

Returns 204 No Content.

Delete API Key

curl -X DELETE "https://apps.aurionai.net/api/v1/api-keys/key_abc123" \
  -H "Authorization: Bearer <dashboard-jwt>"

Returns 204 No Content.

Best Practices

• Least privilege — Only grant the scopes your integration needs
• Rotate regularly — Create new keys and retire old ones periodically
• Never commit keys — Use environment variables, not source code
• One key per integration — Makes it easy to revoke access per integration