AI Gateway API

The Auris AI Gateway exposes a set of API endpoints that power the built-in administrative assistant available in the Console. The assistant can answer questions about your tenant configuration, produce structured action plans, execute read operations autonomously, and request human approval before taking any write action.

All AI traffic is routed through a LiteLLM proxy container (litellm:4000) that normalises provider APIs, enforces per-application virtual key budgets, and provides a unified model identifier (altovar-default). Swapping the underlying model or provider is a configuration change — no application code changes are required.

All endpoints in this group require the admin:all permission and the x-tenant header.

Chat

Request body

Message object

{ "role": "user", "content": "How many active sessions does [email protected] have?" }

Response body

{
  "reply": "Alice currently has 3 active sessions across 2 devices.",
  "reasoning": "...",
  "reasoningDurationMs": 1240,
  "toolCalls": [
    {
      "id": "call_abc",
      "name": "list_sessions",
      "arguments": "{\"userId\":\"usr_abc123\"}",
      "result": "{\"sessions\":[\"...\"]}",
      "durationMs": 182
    }
  ]
}

Modes

The mode field changes the assistant’s behaviour and prompt strategy.

Effort levels

The effort field controls the model’s token budget, temperature, and whether chain-of-thought reasoning is enabled.

Setting reasoning: false forces reasoning effort to minimal regardless of effort. Setting reasoning: true raises it to at least medium.

Tool loop

In agent mode the assistant has access to a set of read-only tools it can invoke autonomously (up to 5 rounds per request). Write actions are never invoked by the model directly — they are always surfaced as an approval request.

Read tools (no approval required):

search_users, get_user, get_user_roles, get_user_groups, list_audit_events, count_active_sessions, list_sessions, list_roles, get_role, list_groups, list_applications, get_application, check_url_connectivity, list_ip_rules, list_webhooks, get_security_defaults, get_tenant_info, list_security_alerts, get_mfa_stats, list_trusted_devices, list_organizations, get_organization, list_sso_connections, list_email_templates, fga_check, fga_list_tuples, list_log_streams, get_log_stream, list_pending_events

Write actions (always require approval):

user_disable, user_enable, session_revoke, session_revoke_all, user_force_password_reset, mfa_reset, ip_rule_block, ip_rule_disable, ip_rule_enable, ip_rule_delete, create_ip_allow_rule, send_password_reset_email, revoke_trusted_device, revoke_all_trusted_devices, acknowledge_security_alert, resolve_security_alert, test_log_stream, enable_log_stream, disable_log_stream, delete_log_stream, application_disable, application_enable, assign_role_to_user, remove_role_from_user, create_user, create_application, create_webhook, enable_webhook, disable_webhook, create_organization, update_organization, create_role, create_group, add_user_to_group, remove_user_from_group, delete_group, add_organization_member, remove_organization_member, update_organization_member_role, send_verification_email, update_security_defaults, update_user, update_application, regenerate_client_secret, delete_user, delete_application, delete_webhook, delete_organization, delete_role, fga_write_tuple, fga_delete_tuple

Platform policy

The optional platformPolicy field scopes down what the assistant is allowed to do for this call. This is useful when embedding the assistant in a context where only a subset of capabilities should be available.

{
  "platformPolicy": {
    "name": "read-only-audit",
    "capabilities": ["list_audit_events", "get_user"],
    "allowRead": true,
    "allowWrite": false,
    "permissionMode": "strict"
  }
}

Clarifying questions

The model may embed a fenced block in its reply to ask a clarifying question before proceeding. The server strips the block from the visible reply and surfaces it in the question field.

The model appends to its text reply:

    ```clarify
    {"id":"q-env","text":"Which environment should I target?","suggestedAnswers":["staging","production"]}

The client should display the question to the operator and re-send the conversation with `questionAnswer: { questionId: "q-env", answer: "production" }`.

---

## Explain

<ApiEndpoint method="POST" path="/api/ai/explain" permission="admin:all">
  Ask the assistant to explain an opaque object in plain language — for example a raw audit log
  entry, a token exchange request, a CIBA callback, or a security event. The object is
  automatically redacted of sensitive keys before being sent to the model.
</ApiEndpoint>

### Request body

```json
{
  "topic": "token-exchange",
  "payload": {
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "requested_token_type": "urn:ietf:params:oauth:token-type:refresh_token"
  },
  "context": { "clientId": "app_billing" },
  "locale": "en"
}

Response body

{
  "success": true,
  "data": {
    "summary": "This is a standard RFC 8693 token exchange request. The caller is trading an existing access token for a refresh token.",
    "findings": [
      "The subject token type is an access token, which is the standard input for this grant.",
      "The requested token type is a refresh token — this extends the session lifetime."
    ],
    "recommendations": [
      "Verify that the client is authorised to perform token exchange (check the allowed_grant_types list for app_billing).",
      "Confirm that the subject token has not expired before processing."
    ],
    "confidence": "high"
  }
}

Action Approvals

When the assistant identifies a write action in the conversation, it does not execute the action immediately. Instead it creates an AiActionApproval record and returns an actionRequest object in the chat response. The operator must explicitly approve or reject the action before it runs.

This design means the assistant can never modify tenant state without a human decision in the loop.

Approval lifecycle

pending  -->  approved  -->  executed
                        -->  failed
         -->  rejected
         -->  expired  (after 10 minutes)

Approval records are retained for 30 days after expiry, then deleted.

Action risk levels

Every write action is assigned a risk level that determines whether step-up authentication is required.

Action request object

When a write action is identified, the chat response includes an actionRequest object:

{
  "actionRequest": {
    "actionId": "apr_hk3mn9xq",
    "actionName": "user_disable",
    "summary": "Disable the account for [email protected] (usr_abc123).",
    "risk": "high",
    "requiresApproval": true,
    "requiresStepUp": false,
    "requiredAcr": null,
    "expiresAt": "2025-02-18T10:10:00Z",
    "approvalToken": "eyJ..."
  }
}

To approve the action inline, resend the conversation with the approval field:

{
  "messages": [...],
  "approval": {
    "actionId": "apr_hk3mn9xq",
    "approvalToken": "eyJ...",
    "approved": true,
    "decisionReason": "Confirmed with the account owner."
  }
}

approvalToken is optional in the inline approval object.

Alternatively, use the dedicated approval endpoints below.

Get Approval

Success response

{
  "actionId": "apr_hk3mn9xq",
  "actionName": "user_disable",
  "summary": "Disable the account for [email protected].",
  "risk": "high",
  "status": "pending",
  "requiresStepUp": false,
  "requiredAcr": null,
  "expiresAt": "2025-02-18T10:10:00Z",
  "createdAt": "2025-02-18T10:00:00Z",
  "approvedAt": null,
  "rejectedAt": null,
  "executedAt": null,
  "decisionReason": null,
  "actionResultStatus": null,
  "actionResultDetails": null
}

The response is the ActionApprovalView object returned directly — there is no ok/data envelope.

Error response (404)

{ "error": "Approval request not found" }

Error codes

Submit Decision

Request body

{
  "approved": true,
  "decisionReason": "Verified with the account owner before proceeding.",
  "stepUp": {
    "challengeId": "chal_xyz789",
    "method": "totp",
    "response": "482910"
  }
}

Success response

{
  "status": "executed",
  "approval": { "actionId": "apr_hk3mn9xq", "actionName": "user_disable", "...": "ActionApprovalView fields" },
  "actionResult": {
    "actionId": "apr_hk3mn9xq",
    "actionName": "user_disable",
    "status": "executed",
    "details": "User usr_abc123 disabled successfully."
  }
}

The response is the ApprovalDecisionResult object returned directly — there is no ok/data envelope. actionResult.details is a plain string (or absent), not a structured object.

The status field in the response reflects the outcome:

Error codes

Step-Up Authentication

Critical-risk actions require the operator to complete an MFA challenge before the action executes. This is separate from the session-level MFA and provides a fresh proof of presence.

Flow

1. The operator calls POST /api/ai/approvals/[id]/decision with approved: true but without stepUp fields.
2. If the action requires step-up (requiresStepUp: true), the server returns HTTP 428:

{
  "status": "step_up_required",
  "approval": { "actionId": "apr_hk3mn9xq", "...": "ActionApprovalView fields" },
  "stepUp": {
    "challengeId": "chal_xyz789",
    "availableMethods": ["totp", "webauthn"],
    "expiresIn": 300,
    "requiredAcr": "aal2"
  }
}

There is no ok/error envelope — the body is the ApprovalDecisionResult object with status: "step_up_required" directly.

3. The client presents the MFA challenge to the operator.
4. The operator completes the challenge. The client re-submits the decision with the stepUp object:

{
  "approved": true,
  "stepUp": {
    "challengeId": "chal_xyz789",
    "method": "totp",
    "response": "482910"
  }
}

5. The server validates the response and, if successful, executes the action.

ACR level hierarchy

The operator’s session ACR must meet or exceed requiredAcr after step-up.

Audit Events

Every state transition in the approval lifecycle emits an audit event visible in the Audit Logs API.

Permissions

All endpoints in this group require the admin:all permission. There is no read-only scoping — the assistant’s ability to query live tenant data and raise approval requests for write actions is considered an administrative capability.

Environment Variables

Related

• Audit Logs API — Query AI_ACTION_* events
• Sessions API — count_active_sessions and session_revoke tools used by the assistant
• Security API — list_security_alerts and IP rule tools used by the assistant
• Fine-Grained Authorization API — fga_check and fga_write_tuple tools used by the assistant