# OAuth Server

Beyond consuming social logins (see [Strategies](/en/docs/auth-strategies)), Sovrium can act **as an OAuth 2.1 / OpenID Connect 1.0 authorization server** — issuing access and refresh tokens for downstream apps and AI/MCP clients that authenticate against your Sovrium identity store.

This is how Sovrium becomes the identity provider for a fleet of apps: one Sovrium instance holds the users, and other services delegate sign-in to it.

## Enabling

The OAuth-server endpoints are **auto-mounted whenever `auth` is configured** — there is nothing to turn on in the schema.

```yaml
auth:
  strategies:
    - type: emailAndPassword
  # OAuth-server endpoints mount automatically under /api/auth/oauth2/* once auth is configured.
```

:::callout
**No schema knobs (yet).** Token lifetimes and other tunables are operator concerns governed by defaults and environment variables, not `app.auth` fields. A future `app.auth.oauthServer.{...}` block may expose select knobs once route wiring stabilizes and we know which settings schema authors actually need. Without `auth` configured, all `/api/auth/*` routes return `404` — there is no identity to authorize.
:::

## Endpoints

The authorization server exposes the standard OAuth 2.1 / OIDC surface under `/api/auth/oauth2/*`, plus discovery documents at well-known paths.

| Method | Path                                      | Purpose                                                  |
| ------ | ----------------------------------------- | -------------------------------------------------------- |
| `GET`  | `/.well-known/oauth-authorization-server` | RFC 8414 authorization-server metadata.                  |
| `GET`  | `/.well-known/openid-configuration`       | OIDC Discovery 1.0 metadata.                             |
| `GET`  | `/.well-known/jwks.json`                  | JSON Web Key Set — public keys for token verification.   |
| `POST` | `/api/auth/oauth2/register`               | RFC 7591 Dynamic Client Registration.                    |
| `GET`  | `/api/auth/oauth2/authorize`              | Authorization endpoint (PKCE-S256 required).             |
| `POST` | `/api/auth/oauth2/consent`                | User-consent acknowledgement.                            |
| `POST` | `/api/auth/oauth2/continue`               | Resume after account-select / post-login.                |
| `POST` | `/api/auth/oauth2/token`                  | Token endpoint (`authorization_code` + `refresh_token`). |
| `GET`  | `/api/auth/oauth2/userinfo`               | OIDC UserInfo claims for the access token.               |
| `POST` | `/api/auth/oauth2/introspect`             | RFC 7662 token introspection.                            |
| `POST` | `/api/auth/oauth2/revoke`                 | RFC 7009 token revocation.                               |

## Defaults

Sovrium tunes the authorization server for self-hosted and AI-client use out of the box:

| Setting                     | Default             | Why                                                                                   |
| --------------------------- | ------------------- | ------------------------------------------------------------------------------------- |
| Dynamic client registration | Enabled             | MCP clients (Claude Desktop, ChatGPT Dev Mode) self-register without operator action. |
| Access token lifetime       | 1 hour              | Industry standard.                                                                    |
| Refresh token lifetime      | 30 days             | Industry standard.                                                                    |
| Login page                  | `/login`            | Sovrium engine page.                                                                  |
| Consent page                | `/oauth/consent`    | Sovrium engine page.                                                                  |
| PKCE                        | Required (S256)     | OAuth 2.1 mandates PKCE for the authorization code flow.                              |
| Token signing               | Rotating EdDSA keys | Signed `id_token`s and access tokens published via the JWKS endpoint.                 |

## MCP & AI Clients

Dynamic client registration is enabled specifically so AI assistants and MCP clients can self-register and obtain tokens, then call your app's MCP-exposed tables (subject to the same [RBAC](/en/docs/auth-roles-rbac) and [table permissions](/en/docs/table-permissions) as any other caller). This lets an AI client act on behalf of a real user, with the same access that user would have in the UI.

## Related Pages

- [Strategies](/en/docs/auth-strategies) — Sovrium as an OAuth _client_ (social login), the inverse direction.
- [Roles & RBAC](/en/docs/auth-roles-rbac) — the access model tokens are bound to.
- [Table Permissions](/en/docs/table-permissions) — what an authorized token can reach.
- [Environment Variables](/en/docs/env-vars) — `AUTH_SECRET` (token signing) and `BASE_URL` (issuer / discovery URLs).