> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skrmir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and Authorization Model

> Responsibility boundaries for AuthN, AuthZ, and Approval in AiOS, including the shared production guardrail chain.

# Authentication and Authorization Model

## Audience

This page is for platform security designers, backend implementers, CLI/Agent integrators, and operators who need to understand production guardrails.

## Goal and Scope

This page defines the roles of AuthN, AuthZ, and Approval, the shared execution chain, and why production mutations require step-up and approval.

## Core Concepts

### AuthN

AuthN handles identity validation, session/token management, and principal derivation.

### AuthZ

AuthZ evaluates action/resource/environment context and returns `allow / deny / require_approval`.

### Approval

Approval records, validates, and audits high-risk production authorizations.

### Task

Task records execution state, progress, and result.
It is not another name for Approval, and it does not replace Approval's decision semantics.
Approval records whether a high-risk action may enter the execution chain; Task records what happens after execution begins.

## Standard Workflow

`AuthN -> AuthZ -> Approval(if required) -> Execute -> Audit`

## Current Control-Plane Status And Approval Surfaces

Before formal OpenAPI publishing, the currently frozen minimal control-plane surfaces are:

* `GET /api/v1/system/info`
* `GET /api/v1/authn/status`
* `GET /api/v1/authz/status`
* `POST /api/v1/approvals`

Boundary rules:

* `/api/v1/system/info` is the platform-level aggregated status entry and does not replace `/healthz` or `/readyz`.
* `authn/authz status` are visibility-only surfaces; they must not expose tokens, session inventories, raw policy tables, or live per-subject authorization results.
* `POST /api/v1/approvals` is now a shipped approval-ticket creation surface; it returns `201 Created` with the full binding context when the approval repository is configured, and a structured `503 Service Unavailable` when it is not.
* The intended behavior for the status surfaces is `200 OK` with a JSON status object that clearly distinguishes `placeholder / ready / degraded`, instead of continuing to return `501 Not Implemented`.

Approval ticket creation must preserve at least these binding semantics:

* required binding: `subject_id`, `env`, `resource_hash`, `action`
* recommended binding: `command_hash`
* a `nonce` must always exist, and the ticket must become invalid after successful consumption

## Planned CLI Example (Not Yet Implemented)

The repository does not currently ship this `approval request` subcommand. The HTTP approval write surface is also still reserved rather than a shipped executable entrypoint.

```bash theme={null}
aios approval request \
  --action deploy.app.update \
  --resource app:project/prod/my-api
```

## Web UI Path

* login and identity context
* production approval flow
* authorization failure and approval-required prompts

## Pitfalls / Risk Notes

* Better Auth does not replace business authorization.
* long-lived JWTs must not carry mutable authorization state.
* any prod write path that bypasses approval is an architectural violation.
* AI and automation access at the platform boundary must remain constrained by AuthZ, Approval, and audit instead of becoming a privileged escape hatch.
* AiOS owns platform-level boundaries; it does not provide fine-grained approval for every coding-tool command inside a DevBox.

## Related Pages

* [API Reference](/en/reference/api/index)
* [Production Step-Up and Approval](/en/agent/production-approval)
* [Logging Architecture](/en/operations/logging)