API.md

# NyxID API Reference

This document describes every HTTP endpoint exposed by the NyxID backend. All endpoints accept and return `application/json` unless otherwise noted.

---

## Table of Contents

- [Authentication](#authentication)
- [Error Format](#error-format)
- [Error Codes](#error-codes)
- [Endpoints](#endpoints)
  - [Health](#health)
  - [Interactive Documentation](#interactive-documentation)
  - [Auth](#auth)
  - [Social Auth](#social-auth)
  - [Users](#users)
  - [API Keys](#api-keys)
  - [Downstream Services](#downstream-services)
  - [SSH](#ssh)
  - [Service Connections](#service-connections)
  - [Service Provider Requirements](#service-provider-requirements)
  - [Providers](#providers)
  - [User Provider Credentials](#user-provider-credentials)
  - [User Provider Tokens](#user-provider-tokens)
  - [Unified Keys (Streamlined Services)](#unified-keys-streamlined-services)
  - [User Endpoints](#user-endpoints)
  - [External API Keys](#external-api-keys)
  - [User Services](#user-services)
  - [Third-party Connector Integration](#third-party-connector-integration)
  - [Bot connection links](#bot-connection-links)
  - [Service Catalog](#service-catalog)
  - [Sessions](#sessions)
  - [Service Endpoints](#service-endpoints)
  - [MCP Config](#mcp-config)
  - [Service Pools](#service-pools)
  - [Proxy](#proxy)
  - [Proxy Service Discovery](#proxy-service-discovery)
  - [LLM Gateway](#llm-gateway)
  - [MFA](#mfa-multi-factor-authentication)
  - [OAuth / OpenID Connect](#oauth--openid-connect)
  - [Token Exchange (Delegated Access)](#token-exchange-delegated-access)
  - [Social Token Exchange (Native Mobile)](#social-token-exchange-native-mobile)
  - [Token Introspection](#token-introspection)
  - [Token Revocation](#token-revocation)
  - [User Consents](#user-consents)
  - [OIDC Discovery](#oidc-discovery)
  - [Admin](#admin)
  - [Admin Roles](#admin-roles)
  - [Admin Groups](#admin-groups)
  - [Admin Service Accounts](#admin-service-accounts)
  - [Catalog Skill Curation](#catalog-skill-curation)
  - [Notification Settings](#notification-settings)
  - [Device Token Management](#device-token-management)
  - [Approval Management](#approval-management)
  - [Telegram New Channel Creation](#telegram-new-channel-creation)
  - [Webhooks](#webhooks)

---

## Authentication

Most endpoints require authentication. NyxID supports three active authentication methods, checked in the following order:

1. **Bearer Token** -- `Authorization: Bearer <access_token>` header
2. **Session Cookie** -- `nyx_session` HttpOnly cookie for first-party browser sessions
3. **API Key** -- `X-API-Key: <key>` header

Endpoints marked **Auth: None** do not require authentication.
Endpoints marked **Auth: Required** require any of the above.
Endpoints marked **Auth: Admin** require an authenticated user with `is_admin = true`.
Endpoints marked **Auth: None** may still require a grant-specific credential in the request body, such as a refresh token.

**Service accounts** authenticate via OAuth2 Client Credentials Grant at `POST /oauth/token` and receive a Bearer token. Service account tokens include an `sa: true` claim and are restricted to proxy, LLM gateway, connections, providers, and delegation endpoints.

---

## Error Format

All errors are returned as JSON with the following structure:

```json
{
  "error": "error_key",
  "error_code": 1000,
  "message": "Human-readable description"
}
```

The `session_token` field is only present when `error_code` is `2002` (MFA required):

```json
{
  "error": "mfa_required",
  "error_code": 2002,
  "message": "MFA verification required",
  "session_token": "temporary_mfa_session_token"
}
```

Internal errors never leak implementation details. The `message` for error codes `1006` and `1007` is always `"An internal error occurred"`.

---

## Error Codes

| Code | Key                        | HTTP Status | Description                              |
|------|----------------------------|-------------|------------------------------------------|
| 1000 | `bad_request`              | 400         | Malformed request                        |
| 1001 | `unauthorized`             | 401         | Missing or invalid credentials           |
| 1002 | `forbidden`                | 403         | Insufficient permissions                 |
| 1003 | `not_found`                | 404         | Resource does not exist                  |
| 1004 | `conflict`                 | 409         | Resource already exists                  |
| 1005 | `rate_limited`             | 429         | Rate limit exceeded                      |
| 1006 | `internal_error`           | 500         | Server error (details redacted)          |
| 1007 | `database_error`           | 500         | Database error (details redacted)        |
| 1008 | `validation_error`         | 400         | Input validation failed                  |
| 2000 | `authentication_failed`    | 401         | Wrong email/password or invalid MFA code |
| 2001 | `token_expired`            | 401         | JWT has expired                          |
| 2002 | `mfa_required`             | 403         | MFA verification needed to complete login|
| 3000 | `pkce_verification_failed` | 400         | PKCE code_verifier mismatch              |
| 3001 | `invalid_redirect_uri`     | 400         | Redirect URI not registered for client   |
| 3002 | `invalid_scope`            | 400         | Requested scope not allowed              |
| 5000 | `service_account_not_found`| 404         | Service account does not exist           |
| 5001 | `service_account_inactive` | 403         | Service account is deactivated           |
| 6000 | `social_auth_failed`       | 400         | Social authentication failed             |
| 6001 | `social_auth_conflict`     | 409         | Social identity could not be linked because it is already reserved by another account |
| 6002 | `social_auth_no_email`     | 400         | No verified email from provider          |
| 6003 | `social_auth_deactivated`  | 403         | Social login account is deactivated      |
| 6004 | `external_token_invalid`   | 400         | External provider token verification failed (signature, expiry, audience, or claims) |
| 6005 | `external_provider_not_configured` | 400  | Provider hint missing or provider not configured on the server |
| 7000 | `approval_required`        | 403         | User approval required (proxy/LLM requests block until decision; this code is used for async status polling) |

---

## Endpoints

### Health

#### GET /health

Returns service health status. No authentication required.

**Auth:** None

**Response:**

```json
{
  "status": "ok",
  "version": "0.5.0"
}
```

**Example:**

```bash
curl http://localhost:3001/health
```

---

### Interactive Documentation

NyxID serves authenticated interactive documentation for both its own API and downstream proxied services.

#### GET /api/v1/docs

Serve the Scalar UI for NyxID's OpenAPI 3.1 document.

**Auth:** Required

**Response:** HTML page

#### GET /api/v1/docs/openapi.json

Return the raw OpenAPI 3.1 document for NyxID.

**Auth:** Required

**Response:** JSON OpenAPI document

#### GET /api/v1/docs/asyncapi.json

Return the raw AsyncAPI 3.0 document for NyxID's streaming transports, including node WebSockets, SSH-over-WebSocket, MCP streamable HTTP, proxy SSE, and LLM SSE.

**Auth:** Required

**Response:** JSON AsyncAPI document

#### GET /api/v1/docs/catalog

Serve the unified downstream API catalog page. The catalog fetches `GET /api/v1/proxy/services` and displays docs availability plus streaming support for each service.

**Auth:** Required

**Response:** HTML page

#### GET /api/v1/proxy/services/{service_id}/docs

Serve the Scalar UI for a downstream service. NyxID selects the service's proxied OpenAPI document when available and falls back to the proxied AsyncAPI document otherwise.

**Auth:** Required

**Path Parameters:**

| Parameter    | Type | Description    |
|--------------|------|----------------|
| `service_id` | UUID | The service ID |

**Response:** HTML page

#### GET /api/v1/proxy/services/{service_id}/openapi.json

Return the downstream OpenAPI document after NyxID rewrites `servers[].url` to point at the authenticated proxy route.

**Auth:** Required

#### GET /api/v1/proxy/services/{service_id}/asyncapi.json

Return the downstream AsyncAPI document with NyxID metadata attached.

**Auth:** Required

See also [API_DISCOVERY.md](./API_DISCOVERY.md) for the operator workflow around discovery, overrides, and proxy-aware testing.

---

### Auth

#### POST /api/v1/auth/register

Create a new user account.

**Auth:** None

**Request Body:**

| Field          | Type   | Required | Description                               |
|----------------|--------|----------|-------------------------------------------|
| `email`        | string | Yes      | Valid email address                       |
| `password`     | string | Yes      | 8-128 characters                          |
| `display_name` | string | No       | User display name                         |

```json
{
  "email": "user@example.com",
  "password": "securepassword123",
  "display_name": "Jane Doe"
}
```

**Response (200):**

```json
{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Registration successful. Please verify your email."
}
```

**Errors:**
- `1004 conflict` -- Email already registered
- `1008 validation_error` -- Invalid email format or password length

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123",
    "display_name": "Jane Doe"
  }'
```

---

#### POST /api/v1/auth/login

Authenticate with email and password.

For first-party browser requests, login creates a server-side session, sets the `nyx_session` cookie, clears legacy browser token cookies, and returns a minimal JSON body.

For token clients such as native mobile apps, send `client: "mobile"` or `client: "token"`. Token clients receive `access_token` and `refresh_token` in the JSON response and should use bearer authentication on subsequent requests.

If the user has MFA enabled and no `mfa_code` is provided, returns a `403` with error code `2002` and a `session_token` for the MFA verification step.

**Auth:** None

**Request Body:**

| Field      | Type   | Required | Description                                    |
|------------|--------|----------|------------------------------------------------|
| `email`    | string | Yes      | User email address                             |
| `password` | string | Yes      | User password (max 128 chars)                  |
| `mfa_code` | string | No       | 6-digit TOTP code (required if MFA is enabled) |
| `client`   | string | No       | `"web"` for browser session mode, `"mobile"` / `"token"` for token response mode |

```json
{
  "email": "user@example.com",
  "password": "securepassword123",
  "client": "web"
}
```

**Response (200, browser session):**

```json
{
  "user_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

**Response Headers (Set-Cookie, browser session):**

```
Set-Cookie: nyx_session=<token>; HttpOnly; SameSite=Lax; Path=/; Max-Age=2592000
Set-Cookie: nyx_access_token=; HttpOnly; SameSite=Lax; Path=/; Max-Age=0
Set-Cookie: nyx_refresh_token=; HttpOnly; SameSite=Lax; Path=/api/v1/auth/refresh; Max-Age=0
```

**Response (200, token client):**

```json
{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 900,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**MFA Challenge Response (403):**

```json
{
  "error": "mfa_required",
  "error_code": 2002,
  "message": "MFA verification required",
  "session_token": "temporary_session_token_here"
}
```

To complete login with MFA, re-send the login request with the `mfa_code` field included.

**Errors:**
- `2000 authentication_failed` -- Wrong email/password or invalid MFA code
- `2002 mfa_required` -- MFA code required (includes `session_token`)
- `1008 validation_error` -- Invalid email format or password too long

**Example:**

```bash
# Browser session login
curl -X POST http://localhost:3001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123",
    "client": "web"
  }'

# Token-client login
curl -X POST http://localhost:3001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123",
    "client": "mobile"
  }'

# Login with MFA
curl -X POST http://localhost:3001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123",
    "mfa_code": "123456",
    "client": "mobile"
  }'
```

---

#### POST /api/v1/auth/logout

Revoke the current session and clear all authentication cookies.

**Auth:** Required

**Response (200):**

```json
{
  "message": "Logged out successfully"
}
```

**Response Headers:** Clears `nyx_session`, `nyx_access_token`, and `nyx_refresh_token` cookies.

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/auth/logout \
  -H "Authorization: Bearer <access_token>"
```

---

#### POST /api/v1/auth/refresh

Exchange a refresh token for a new access token. This endpoint is for token clients such as native mobile apps. The refresh token is supplied in the JSON body. Implements token rotation: the old refresh token is invalidated and a new one is issued.

**Auth:** None

**Request Body:**

| Field           | Type   | Required | Description                              |
|-----------------|--------|----------|------------------------------------------|
| `refresh_token` | string | Yes      | A valid refresh token                    |

```json
{
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**Response (200):**

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 900,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**Errors:**
- `1001 unauthorized` -- No refresh token provided or token revoked
- `2001 token_expired` -- Refresh token has expired

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'
```

---

#### POST /api/v1/auth/device/request

Start a legacy account-only device login. New clients use the isolated
[v2 exchange](#selectable-device-login-v2) below to let the human choose the
grant. This route remains compatible with existing account-only clients.

**Auth:** None

**Request Body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `client_label` | string | No | Short client name shown to the approving user |
| `client_user_agent` | string | No | Sanitized client context shown during review |

```json
{
  "supports_grant_choice": false,
  "client_label": "Desktop workstation",
  "client_user_agent": "desktop-app/1.4"
}
```

**Response (200):**

```json
{
  "device_code": "nyx_adc_<opaque-secret>",
  "user_code": "7KM2RQ9D",
  "verification_uri": "https://app.nyxid.dev/login/device",
  "verification_uri_complete": "https://app.nyxid.dev/login/device?user_code=7KM2RQ9D",
  "expires_in": 600,
  "interval": 5
}
```

The `device_code` is a secret and must not be logged or displayed. The `user_code` is for manual entry at `verification_uri`. Codes expire 10 minutes after issuance. QR/deep links using `verification_uri_complete` prefill the web approval page and mobile app; they never trigger preview or approval. The web page validates before formatting, seeds once, and removes `user_code` from the URL with replace navigation. Malformed codes leave an empty input with an explanation. After Continue, review echoes the code and asks the human to match it against the requesting device or terminal and reject a mismatch (RFC 8628 §§3.3.1, 5.4). Decisions remain explicit and throttled at >=750 ms. `/login/code` only mints codes and has no prefill input.

#### POST /api/v1/auth/device/poll

Poll for approval and atomically receive the first-party token pair once. This public contract is stable and versioned with `/api/v1`.

**Auth:** None

```json
{
  "device_code": "nyx_adc_<opaque-secret>"
}
```

**Response (200, approved):**

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900
}
```

Poll no faster than the `interval` returned by `/request`. A `11202` response means approval is still pending. On `11203`, add 5 seconds to the client's current interval before polling again; each additional premature poll increases the server-side interval by another 5 seconds. Stop on denied, expired, or already-delivered responses. Token delivery is single-use: the first approved poll receives the tokens and every later poll returns `11205`.

| Code | Key | HTTP | Meaning |
|------|-----|------|---------|
| `11200` | `auth_device_code_not_found` | 404 | Device code does not exist |
| `11201` | `auth_device_expired_token` | 410 | Device code reached its 10-minute TTL |
| `11202` | `auth_device_authorization_pending` | 400 | User decision is still pending |
| `11203` | `auth_device_slow_down` | 429 | Client polled before the current interval elapsed |
| `11204` | `auth_device_access_denied` | 403 | User denied the login request |
| `11205` | `auth_device_already_delivered` | 410 | The token pair was already delivered to one poller |
| `11206` | `auth_device_rate_limited` | 429 | Endpoint rate limit was exceeded |
| `11207` | `auth_device_user_code_invalid` | 400 | The first-party review UI supplied an invalid user code |

#### POST /api/v1/auth/device/poll-web

First-party browser delivery variant for the NyxID web login page. Integrators and desktop/CLI clients must continue using `/auth/device/poll`, which returns the token pair.

**Auth:** None (the response establishes the browser session)

```json
{
  "device_code": "nyx_adc_<opaque-secret>"
}
```

On a successful approved claim, the endpoint atomically marks the request delivered, revokes the approval-created JWT session, creates a fresh browser session using the polling browser's IP and user agent, and returns:

```json
{ "ok": true }
```

The response sets the standard `nyx_session` cookie (`HttpOnly`, `SameSite=Lax`, `Path=/`, and the deployment's normal `Secure`/`Domain` settings). Access and refresh tokens are never returned in the body. Pending, denied, expired, already-delivered, and rate-limit outcomes use the same `11200`-`11207` error contract as `/poll`; a claim delivered through either variant makes the other variant return `11205`.

#### POST /api/v1/auth/device/preview

Fetch the non-mutating anti-phishing context shown by first-party review surfaces.

**Auth:** None

```json
{
  "user_code": "7KM2-RQ9D"
}
```

**Response (200):**

```json
{
  "client_label": "Desktop workstation",
  "client_user_agent": "desktop-app/1.4",
  "client_ip": "203.0.113.24",
  "initiated_at": "2026-08-20T08:15:00Z",
  "expires_at": "2026-08-20T08:25:00Z",
  "status": "pending"
}
```

`client_label` and `client_user_agent` are requester-supplied free text. `client_ip` is the server-resolved request address observed at `/request`; legacy rows return `null`. All auth-device rows expire after 10 minutes.

`supports_grant_choice` is an explicit capability advertisement. It is `true`
only for grant-capable `/auth/device/v2/request` rows and is `false` for
legacy rows. Clients must use this field instead of inspecting the public code
format. Legacy and v2 requests default to eight normalized characters for installed
app compatibility. `AUTH_DEVICE_EIGHT_CHAR_CODES=false` restores the old
nine-character v2 marker during rollout rollback. Old readers and non-reserving
writers must be drained before eight-character v2 issuance (see ADR-015).

#### POST /api/v1/auth/device/approve

Atomically approve a pending request and prepare a first-party token pair for one poller.

**Auth:** Human JWT session only

```json
{
  "user_code": "7KM2-RQ9D"
}
```

**Response (200):** `{ "ok": true }`

#### POST /api/v1/auth/device/deny

Atomically reject a pending request. No tokens are minted, and the requester's next poll returns `11204` immediately.

**Auth:** Human JWT session only

```json
{
  "user_code": "7KM2-RQ9D"
}
```

**Response (200):** `{ "ok": true }`

Approve and deny use the same pending-status guard, so exactly one wins a concurrent decision. API-key, service-account, delegated, and relay credentials are rejected before either decision handler runs. Integrators should direct users to `verification_uri`; these are first-party review endpoints.

#### Selectable Device Login V2

Options expose per-key effective bindings and platform availability metadata.
`allow_auto_connected_services` covers active same-owner rows with either
`source=auto_provision` or `credential_binding=platform`, including future rows.
This durable grant is disclosed as extra access; unreported provider scopes are
never exact. New-client approval submits snapshots for explicit and current
implied connections. See [DEVICE_LOGIN_PROTOCOL.md](DEVICE_LOGIN_PROTOCOL.md).

The browser hint allowlist, three-step approval and additive consent snapshots are documented in [DEVICE_LOGIN_PROTOCOL.md](DEVICE_LOGIN_PROTOCOL.md).

Plain `nyxid login` deliberately defaults to this exchange: it provides requester attribution (IP, timezone, origin, screen) and human choice of account access or a restricted Agent Key. `nyxid login --callback` opts into the legacy local callback, which grants full account access without requester review. The CLI prints/opens only the bare verification URI for manual code entry; `--clipboard` copies the user code for pasting, except in JSON/no-wait modes, which do not copy or open a browser.

New clients start with `POST /api/v1/auth/device/v2/request`, using the same
client-context body as the legacy request, plus optional `requested_profile`.
The response has the same fields, with a `nyx_adc2_` poll secret and a
human code: `2-XXXX-XXXX` in compatibility mode, or `XXXX-XXXX` after the
staged issuance gate is enabled. Use `/auth/device/v2/poll` or the browser-only
`/auth/device/v2/poll-web` with `{"device_code":"nyx_adc2_<secret>"}`.

V2 requests live in separate storage. Old replicas return an unsupported route
without consuming new grants, and old TTL indexes cannot remove v2 cleanup
work. Clients must not retry a v2 request through the legacy poll route.
Legacy requests only offer account access.

The shared public `/auth/device/preview` checks both protocol collections, rejects ambiguous codes, and
includes the requested profile and sanitized requester context. Human decisions
require a first-party personal session or an access JWT without an OAuth client
ID. Third-party OAuth, delegated, relay, service-account and API-key credentials
cannot approve or mint login grants.

| Method and path | Body | Result |
|---|---|---|
| `POST /auth/device/options` | `{"user_code":"XXXX-XXXX"}` | Eligible personal/org keys and resource choices |
| `POST /auth/device/approve` | `{"user_code":"XXXX-XXXX"}` | Full account approval |
| `POST /auth/device/approve-agent-key` | Human code, `selection`, optional `credential_expires_at` | Restricted child credential approval |
| `POST /auth/device/deny` | Human code | Denial without issuance |

`selection` uses the Agent Key login contract: `{"kind":"existing","api_key_id":"<UUID>"}`
or a `kind: "new"` selection containing the confirmed key permissions. Restricted
decisions use a distinct fail-closed route so an old replica cannot silently
interpret that choice as full account approval. Creation and delivery revalidate
eligibility and effective authority.

Successful CLI polling returns a tagged union. `auth_kind: "account_session"`
includes `access_token`, `refresh_token`, `token_type` and `expires_in`.
`auth_kind: "agent_key"` includes `credential`, `credential_id`,
`credential_expires_at`, `label` and safe `api_key` metadata. Explicit Agent Key
clients must reject an account grant. The existing device error contract applies;
clients persist server backoff and stop on terminal outcomes.

Browser account delivery returns `{"ok":true,"auth_kind":"account_session"}`
and a cookie. Claim, bearer-session revocation and cookie-session insertion are
one transaction. Browser restricted delivery returns
`{"ok":false,"auth_kind":"agent_key","login_code":{"request_id":"<UUID>","code":"XXXX-XXXX","expires_at":"<RFC3339>"}}`.
This code hands the credential to `nyxid login --code`; it never establishes an
account cookie. Creating the handoff extends the initial 60-second delivery
window to five minutes after approval; repeated handoff calls never extend that
fixed deadline. Browser
handoff and direct CLI delivery race atomically, with exactly one recipient.

KMS failure before delivery preserves retryability. Abandoned approvals revoke
their issued session or child; parent key configuration and other consumers
remain intact. Cleanup completes before terminal TTL removal.

#### One-Time Login Codes

An authenticated human can create a five-minute code before opening a CLI. All
paths below are under `/api/v1`; only redemption is public.

| Method and path | Body or result |
|---|---|
| `POST /auth/login-code/options` | Eligible Agent Keys and resource choices |
| `POST /auth/login-code` | `{"auth_kind":"account_session"}` or `{"auth_kind":"agent_key","selection":{...},"credential_expires_at":null}` |
| `POST /auth/login-code/redeem` | `{"code":"XXXX-XXXX","requested_profile":"work","client_label":"Workstation"}` plus optional client context |
| `GET /auth/login-code/{id}` | Issuer-only status and sanitized redemption context; no code or credential |
| `DELETE /auth/login-code/{id}` | Cancel a pending code |
| `POST /auth/login-code/{id}/revoke` | Revoke its delivered account session or child credential |

Mint returns `request_id`, the secret `code` shown once, and `expires_at`.
Redemption returns the same tagged delivery as v2 polling. Issuance and claim are
one transaction; concurrent redemption has one winner and failures leave no
orphan grant. Mint/redeem are limited by source and issuer, including invalid-code
attempts. Terminal status is `redeemed`, `cancelled`, `expired` or `revoked`;
`can_revoke` indicates delivered credentials. The numeric error definitions are
authoritative in `backend/src/errors/mod.rs`. Codes belong in neither URLs, logs,
telemetry nor persistent browser storage.

First-party access JWTs carry `sid`. Protected requests and refresh validate the
bound session's liveness, so issuer revocation invalidates both existing and
refreshed access tokens and cascades to MCP sessions. Legacy first-party tokens
without `sid` retain their existing compatibility behavior.

---

#### POST /api/v1/auth/verify-email

Verify a user's email address using the token sent during registration.

**Auth:** None

**Request Body:**

| Field   | Type   | Required | Description                         |
|---------|--------|----------|-------------------------------------|
| `token` | string | Yes      | Email verification token            |

```json
{
  "token": "verification-token-here"
}
```

**Response (200):**

```json
{
  "message": "Email verified successfully"
}
```

**Errors:**
- `1000 bad_request` -- Missing or invalid token
- `1003 not_found` -- Token not found or already used

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{"token": "verification-token-here"}'
```

---

#### POST /api/v1/auth/forgot-password

Request a password reset. Always returns success to prevent email enumeration.

**Auth:** None

**Request Body:**

| Field   | Type   | Required | Description           |
|---------|--------|----------|-----------------------|
| `email` | string | Yes      | User email address    |

```json
{
  "email": "user@example.com"
}
```

**Response (200):**

```json
{
  "message": "If an account exists with that email, a password reset link has been sent."
}
```

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
```

---

#### POST /api/v1/auth/reset-password

Reset a user's password using a valid reset token.

**Auth:** None

**Request Body:**

| Field          | Type   | Required | Description                    |
|----------------|--------|----------|--------------------------------|
| `token`        | string | Yes      | Password reset token           |
| `new_password` | string | Yes      | New password (8-128 characters)|

```json
{
  "token": "reset-token-here",
  "new_password": "newsecurepassword123"
}
```

**Response (200):**

```json
{
  "message": "Password reset successfully"
}
```

**Errors:**
- `1000 bad_request` -- Missing token or password too short/long
- `1003 not_found` -- Token not found, expired, or already used

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{"token": "reset-token-here", "new_password": "newsecurepassword123"}'
```

---

#### POST /api/v1/auth/setup

One-time bootstrap endpoint to create the initial admin user. Only works when the users collection is completely empty. After the first user is created, this endpoint returns 403 Forbidden.

**Auth:** None

**Request Body:**

| Field          | Type   | Required | Description                               |
|----------------|--------|----------|-------------------------------------------|
| `email`        | string | Yes      | Valid email address                       |
| `password`     | string | Yes      | 8-128 characters                          |
| `display_name` | string | No       | Admin display name                        |

```json
{
  "email": "admin@example.com",
  "password": "secureadminpassword123",
  "display_name": "Admin"
}
```

**Response (200):**

```json
{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Admin account created successfully."
}
```

**Errors:**
- `1002 forbidden` -- Users already exist (setup already completed)
- `1008 validation_error` -- Invalid email format or password length

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/auth/setup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "secureadminpassword123",
    "display_name": "Admin"
  }'
```

---

### Social Auth

Social login supports two modes:
- First-party web: browser redirect flow that creates a NyxID session and sets only the `nyx_session` cookie.
- Native mobile: deep-link redirect flow via `?client=mobile&redirect_uri=...` that returns access and refresh tokens in the success redirect URL.

**Flow:**

1. Frontend navigates to `GET /api/v1/auth/social/{provider}` (e.g., via a "Sign in with GitHub" button)
2. Backend generates a CSRF state token, stores it as a cookie, and redirects (302) to the provider's authorization page
3. User authorizes the application on the provider's site
4. Provider redirects back to `GET /api/v1/auth/social/{provider}/callback` with `code` and `state` query parameters
5. Backend validates the state token, exchanges the code for an access token, fetches the user's profile
6. Backend finds or creates a user, then either creates a browser session and redirects to the frontend or returns tokens via a mobile deep link

#### GET /api/v1/auth/social/{provider}

Initiate an OAuth 2.0 authorization flow with a social provider.

**Auth:** None

**Path Parameters:**

| Parameter  | Type   | Description                            |
|------------|--------|----------------------------------------|
| `provider` | string | Social provider: `"github"` or `"google"` |

**Response (302):** Redirects to the provider's authorization page. Sets the `nyx_social_state` HttpOnly cookie containing the CSRF state token.

**Mobile Query Parameters:**

| Parameter      | Type   | Description |
|----------------|--------|-------------|
| `client`       | string | Set to `"mobile"` for native mobile deep-link mode |
| `redirect_uri` | string | Required for mobile mode. Must be an allowed `nyxid://` or `exp://` deep link |

**Errors:**
- `6000 social_auth_failed` -- Provider not configured (missing client ID/secret) or unsupported provider

**Example:**

Navigate in browser:
```
http://localhost:3001/api/v1/auth/social/github
http://localhost:3001/api/v1/auth/social/google
```

---

#### GET /api/v1/auth/social/{provider}/callback

OAuth callback handler. Called by the provider after user authorization.

**Auth:** None (called by the OAuth provider redirect)

**Path Parameters:**

| Parameter  | Type   | Description                            |
|------------|--------|----------------------------------------|
| `provider` | string | Social provider: `"github"` or `"google"` |

**Query Parameters:**

| Parameter | Type   | Description                                         |
|-----------|--------|-----------------------------------------------------|
| `code`    | string | Authorization code from the provider                |
| `state`   | string | CSRF state token (must match the `nyx_social_state` cookie) |
| `error`   | string | Error code from the provider (if authorization was denied) |

**Response (302 on success, web):** Redirects to the frontend root and sets the `nyx_session` cookie.

**Response (302 on success, mobile):** Redirects to the provided deep link with `status=success`, `provider`, `user_id`, `access_token`, `refresh_token`, and `expires_in` query parameters.

**Response (302 on error):** Redirects to `{FRONTEND_URL}/login?error={error_key}`.

Possible error keys in the redirect:

| Scenario                          | Error key in redirect         |
|-----------------------------------|-------------------------------|
| Provider returned an error        | `social_auth_denied`          |
| Missing code or state parameter   | `social_auth_invalid`         |
| State/CSRF token mismatch         | `social_auth_csrf`            |
| Code exchange failed              | `social_auth_exchange`        |
| Profile fetch failed              | `social_auth_profile`         |
| Social identity could not be linked | `social_auth_conflict`      |
| No verified email from provider   | `social_auth_no_email`        |
| Provider not configured           | `social_auth_unavailable`     |
| Unsupported provider name         | `social_auth_unsupported`     |
| Account is deactivated            | `social_auth_deactivated`     |

**Notes:**
- If a user with the same verified email already exists, the social identity is linked to that account
- If the matched account was previously linked to a different social provider, NyxID re-links it to the current provider
- `social_auth_conflict` is reserved for write-time identity collisions (for example, if the provider identity is already bound to another account)
- New users created via social login have `email_verified = true` (provider verified the email) and no password set
- Existing email/password accounts keep their password login path after social linking

---

### Users

#### GET /api/v1/users/me

Returns the profile of the currently authenticated user.

**Auth:** Required

**Response (200):**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "display_name": "Jane Doe",
  "avatar_url": "https://example.com/avatar.jpg",
  "email_verified": true,
  "mfa_enabled": false,
  "created_at": "2025-01-15T10:30:00+00:00",
  "last_login_at": "2025-06-01T14:22:00+00:00"
}
```

**Example:**

```bash
curl http://localhost:3001/api/v1/users/me \
  -H "Authorization: Bearer <access_token>"
```

---

#### PUT /api/v1/users/me

Update the profile of the currently authenticated user.

**Auth:** Required

**Request Body:**

| Field          | Type   | Required | Description                                  |
|----------------|--------|----------|----------------------------------------------|
| `display_name` | string | No       | New display name (max 200 chars)             |
| `avatar_url`   | string | No       | New avatar URL (must use https:// or http://) |

```json
{
  "display_name": "Jane Smith",
  "avatar_url": "https://example.com/new-avatar.jpg"
}
```

**Response (200):**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "display_name": "Jane Smith",
  "avatar_url": "https://example.com/new-avatar.jpg",
  "message": "Profile updated successfully"
}
```

**Errors:**
- `1008 validation_error` -- Display name too long, or avatar URL has invalid scheme

**Example:**

```bash
curl -X PUT http://localhost:3001/api/v1/users/me \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "Jane Smith"}'
```

---

### API Keys

#### GET /api/v1/api-keys

List all API keys for the authenticated user. The full key value is never returned after creation.

**Auth:** Required

**Response (200):**

```json
{
  "keys": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Production API Key",
      "key_prefix": "nyx_k_a1b2c3d4",
      "scopes": "read write",
      "last_used_at": "2025-06-01T14:22:00+00:00",
      "expires_at": null,
      "is_active": true,
      "created_at": "2025-01-15T10:30:00+00:00"
    }
  ]
}
```

**Example:**

```bash
curl http://localhost:3001/api/v1/api-keys \
  -H "Authorization: Bearer <access_token>"
```

---

#### POST /api/v1/api-keys

Create a new API key. The full key is returned only in this response and cannot be retrieved again.

**Auth:** Required

**Request Body:**

| Field        | Type   | Required | Description                                  |
|--------------|--------|----------|----------------------------------------------|
| `name`       | string | Yes      | Human-readable name for the key              |
| `scopes`     | string | No       | Space-separated scopes (default: `"read"`)   |
| `expires_at` | string | No       | ISO 8601 expiration datetime                 |
| `description` | string | No      | Optional description of key purpose          |
| `allowed_service_ids` | string[] | No | UserService IDs this key can proxy. Only enforced when `allow_all_services: false`. Providing values without also setting `allow_all_services: false` will silently store the list but **not** scope the key. |
| `allowed_node_ids` | string[] | No | Node IDs this key can route through. Only enforced when `allow_all_nodes: false`. Providing values without also setting `allow_all_nodes: false` will silently store the list but **not** scope the key. |
| `allow_all_services` | boolean | No | If true, key can access all user's external services (default: true) |
| `allow_all_nodes` | boolean | No | If true, key can route through all user's nodes (default: true) |

> **Scoping API keys:** To create a scoped key you must set BOTH `allow_all_services: false` AND a non-empty `allowed_service_ids` (and likewise `allow_all_nodes: false` + `allowed_node_ids` for node scoping). Either alone is a no-op. The defaults exist for backward compatibility with pre-scope keys, so a naive payload yields a broad key.

Broad key (default):

```json
{
  "name": "Production API Key",
  "scopes": "read write",
  "expires_at": "2026-01-01T00:00:00Z"
}
```

Scoped key:

```json
{
  "name": "Scoped Key",
  "scopes": "proxy",
  "allow_all_services": false,
  "allowed_service_ids": ["<UserService.id>", "..."]
}
```

**Response (200):**

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Production API Key",
  "key_prefix": "nyx_k_a1b2c3d4",
  "full_key": "nyx_k_a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef12345678",
  "scopes": "read write",
  "created_at": "2025-06-01T10:00:00+00:00"
}
```

**Errors:**
- `1008 validation_error` -- Empty name

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/api-keys \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Key", "scopes": "read"}'
```

---

#### DELETE /api/v1/api-keys/{key_id}

Deactivate an API key. The key can no longer be used for authentication after this operation.

**Auth:** Required

**Path Parameters:**

| Parameter | Type | Description      |
|-----------|------|------------------|
| `key_id`  | UUID | The API key ID   |

**Response (200):**

```json
{
  "message": "API key deleted"
}
```

**Errors:**
- `1003 not_found` -- Key does not exist or does not belong to the user

**Example:**

```bash
curl -X DELETE http://localhost:3001/api/v1/api-keys/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <access_token>"
```

---

#### POST /api/v1/api-keys/{key_id}/rotate

Rotate an API key: deactivate the existing key and create a new one with the same name and scopes. The new full key is returned in the response.

**Auth:** Required

**Path Parameters:**

| Parameter | Type | Description      |
|-----------|------|------------------|
| `key_id`  | UUID | The API key ID   |

**Response (200):**

```json
{
  "id": "new-uuid-here",
  "name": "Production API Key",
  "key_prefix": "nyx_k_b2c3d4e5",
  "full_key": "nyx_k_b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef12345678ab",
  "scopes": "read write",
  "created_at": "2025-06-02T10:00:00+00:00"
}
```

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/api-keys/a1b2c3d4-e5f6-7890-abcd-ef1234567890/rotate \
  -H "Authorization: Bearer <access_token>"
```

---

### Downstream Services

#### GET /api/v1/services

List all active downstream services. Supports optional filtering by service category.

**Auth:** Required

**Query Parameters:**

| Parameter  | Type   | Required | Description                                           |
|------------|--------|----------|-------------------------------------------------------|
| `category` | string | No       | Filter by service category: `provider`, `connection`, or `internal`. Omit for all. |

**Response (200):**

```json
{
  "services": [
    {
      "id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
      "name": "Stripe API",
      "slug": "stripe",
      "description": "Payment processing",
      "base_url": "https://api.stripe.com",
      "auth_method": "header",
      "auth_type": "api_key",
      "auth_key_name": "Authorization",
      "is_active": true,
      "oauth_client_id": null,
      "openapi_spec_url": null,
      "api_spec_url": null,
      "asyncapi_spec_url": null,
      "streaming_supported": false,
      "service_category": "connection",
      "requires_user_credential": true,
      "identity_propagation_mode": "none",
      "identity_include_user_id": false,
      "identity_include_email": false,
      "identity_include_name": false,
      "identity_jwt_audience": null,
      "created_by": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2025-01-15T10:30:00+00:00",
      "updated_at": "2025-01-15T10:30:00+00:00"
    }
  ]
}
```

**Example:**

```bash
# List all services
curl http://localhost:3001/api/v1/services \
  -H "Authorization: Bearer <access_token>"

# List only connectable services
curl "http://localhost:3001/api/v1/services?category=connection" \
  -H "Authorization: Bearer <access_token>"
```

---

#### POST /api/v1/services

Register a new downstream service. The credential is encrypted with AES-256-GCM before storage.

Set `service_type` to `"http"` for the existing HTTP/API flow or `"ssh"` for first-class SSH services. HTTP services use `base_url`, `auth_type`, and optional spec URLs; SSH services use an embedded `ssh_config` object instead.

When `auth_type` (or `auth_method`) is set to `"oidc"`, NyxID automatically provisions an OAuth client for the service, generates a client secret, and sets the default redirect URI to `{base_url}/callback`. No `credential` field is needed for OIDC services.

**Auth:** Admin

**Request Body:**

| Field              | Type   | Required | Description                                                                           |
|--------------------|--------|----------|---------------------------------------------------------------------------------------|
| `name`             | string | Yes      | Service display name (max 200 chars)                                                  |
| `slug`             | string | No       | URL-safe identifier (max 100 chars, unique). Auto-derived from `name` if omitted.     |
| `description`      | string | No       | Service description                                                                   |
| `service_type`     | string | No       | `"http"` (default) or `"ssh"`                                                         |
| `base_url`         | string | HTTP only | Downstream service base URL (max 2048 chars). Must not point to private/internal IPs. |
| `auth_type`        | string | HTTP only | One of: `api_key`, `oauth2`/`bearer`, `basic`, `oidc`, `header`, `query`. Default: `header`. Alias: `auth_method`. |
| `auth_key_name`    | string | HTTP only | Header or query param name. Defaults based on `auth_type`.                            |
| `credential`       | string | HTTP only | API key, token, or `user:password` for basic. Not needed for OIDC services.           |
| `service_category` | string | No       | `"connection"` or `"internal"` for SSH services; `"connection"` (default), `"internal"`, or `"provider"` for HTTP. |
| `ssh_config`       | object | SSH only | SSH target configuration with `host`, `port`, `certificate_auth_enabled`, `certificate_ttl_minutes`, and `allowed_principals` |

**Auth Type Mapping:**

| `auth_type` value  | Internal `auth_method` | Default `auth_key_name` | Behavior                                            |
|--------------------|------------------------|-------------------------|-----------------------------------------------------|
| `api_key` / `header` | `header`             | `X-API-Key`             | Adds `auth_key_name: credential` as a request header|
| `oauth2` / `bearer`  | `bearer`             | `Authorization`         | Adds `Authorization: Bearer credential` header      |
| `query`              | `query`              | `api_key`               | Appends `?auth_key_name=credential` to the URL      |
| `basic`              | `basic`              | `Authorization`         | Sends HTTP Basic Auth (credential = `user:password`) |
| `oidc`               | `oidc`               | `X-API-Key`             | Auto-provisions OAuth client; uses OIDC flow        |

**Service Category Rules:**

| `service_category` | When to use | `requires_user_credential` | User can connect? |
|--------------------|-------------|----------------------------|-------------------|
| `connection` (default) | External services users connect to with their own credentials | `true` | Yes (must supply credential) |
| `internal` | Services using a master credential managed by admin | `false` | Yes (enable only, no credential) |
| `provider` | OIDC services (auto-assigned when `auth_type` is `oidc`) | `false` | No (admin-managed) |

**Example (connection service with API key):**

```json
{
  "name": "Stripe API",
  "slug": "stripe",
  "description": "Payment processing",
  "base_url": "https://api.stripe.com",
  "auth_type": "api_key",
  "credential": "sk-master-key-here",
  "service_category": "connection"
}
```

**Example (internal service):**

```json
{
  "name": "Internal Analytics",
  "base_url": "https://analytics.internal.example.com",
  "auth_type": "bearer",
  "credential": "internal-master-token",
  "service_category": "internal"
}
```

**Example (OIDC service):**

```json
{
  "name": "Customer Portal",
  "base_url": "https://portal.example.com",
  "auth_type": "oidc"
}
```

**Example (SSH service):**

```json
{
  "name": "Production Bastion",
  "service_type": "ssh",
  "service_category": "internal",
  "ssh_config": {
    "host": "ssh.internal.example",
    "port": 22,
    "certificate_auth_enabled": true,
    "certificate_ttl_minutes": 30,
    "allowed_principals": ["ubuntu"]
  }
}
```

**Response (200):**

```json
{
  "id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
  "name": "Stripe API",
  "slug": "stripe",
  "description": "Payment processing",
  "base_url": "https://api.stripe.com",
  "service_type": "http",
  "auth_method": "header",
  "auth_type": "api_key",
  "auth_key_name": "X-API-Key",
  "is_active": true,
  "oauth_client_id": null,
  "openapi_spec_url": null,
  "api_spec_url": null,
  "asyncapi_spec_url": null,
  "streaming_supported": false,
  "ssh_config": null,
  "service_category": "connection",
  "requires_user_credential": true,
  "identity_propagation_mode": "none",
  "identity_include_user_id": false,
  "identity_include_email": false,
  "identity_include_name": false,
  "identity_jwt_audience": null,
  "created_by": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2025-06-01T10:00:00+00:00",
  "updated_at": "2025-06-01T10:00:00+00:00"
}
```

For OIDC services, `oauth_client_id` will contain the auto-provisioned OAuth client ID and `service_category` will be `"provider"`.
For SSH services, `service_type` is `"ssh"`, `auth_method` is `"none"`, `auth_type` is `"ssh"`, `base_url` is derived as `ssh://host:port`, `requires_user_credential` is `false`, and `ssh_config` contains the live SSH settings plus the CA public key.
NyxID also probes the service's `base_url` for OpenAPI and AsyncAPI documents at creation time and populates `openapi_spec_url`, `asyncapi_spec_url`, and `streaming_supported` when discovery succeeds.

**Errors:**
- `1002 forbidden` -- User is not an admin
- `1004 conflict` -- Slug already exists
- `1008 validation_error` -- Missing required fields, invalid auth_type, slug too long, or SSRF-blocked URL

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/services \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytics API",
    "slug": "analytics",
    "base_url": "https://analytics.example.com",
    "auth_type": "api_key",
    "credential": "secret-api-key"
  }'
```

---

#### GET /api/v1/services/{service_id}

Get a single downstream service by ID.

**Auth:** Required

**Path Parameters:**

| Parameter    | Type | Description    |
|--------------|------|----------------|
| `service_id` | UUID | The service ID |

**Response (200):**

```json
{
  "id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
  "name": "Internal Analytics API",
  "slug": "analytics",
  "description": "Company analytics service",
  "base_url": "https://analytics.example.com",
  "auth_method": "header",
  "auth_type": "api_key",
  "auth_key_name": "X-API-Key",
  "is_active": true,
  "oauth_client_id": null,
  "openapi_spec_url": null,
  "api_spec_url": null,
  "asyncapi_spec_url": null,
  "streaming_supported": false,
  "service_category": "connection",
  "requires_user_credential": true,
  "identity_propagation_mode": "none",
  "identity_include_user_id": false,
  "identity_include_email": false,
  "identity_include_name": false,
  "identity_jwt_audience": null,
  "created_by": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2025-06-01T10:00:00+00:00",
  "updated_at": "2025-06-01T10:00:00+00:00"
}
```

**Errors:**
- `1003 not_found` -- Service does not exist

**Example:**

```bash
curl http://localhost:3001/api/v1/services/d1e2f3a4-b5c6-7890-1234-567890abcdef \
  -H "Authorization: Bearer <access_token>"
```

---

#### PUT /api/v1/services/{service_id}

Update a downstream service. Only the provided fields are updated (partial update). HTTP services accept the existing `base_url`, docs, and identity propagation fields; SSH services accept a replacement `ssh_config` object. If the service is an OIDC service and `base_url` is changed, the default redirect URI on the associated OAuth client is automatically updated.

**Auth:** Admin (or service creator)

**Path Parameters:**

| Parameter    | Type | Description    |
|--------------|------|----------------|
| `service_id` | UUID | The service ID |

**Request Body:**

| Field         | Type    | Required | Description                                     |
|---------------|---------|----------|-------------------------------------------------|
| `name`         | string  | No       | New display name (1-200 chars)                                          |
| `description`  | string  | No       | New description (max 500 chars)                                         |
| `base_url`     | string  | No       | New base URL (max 2048 chars, SSRF-validated)                           |
| `is_active`    | boolean | No       | Enable or disable the service                                           |
| `openapi_spec_url` | string  | No       | URL to an OpenAPI/Swagger spec for endpoint discovery (max 2048 chars). The legacy alias `api_spec_url` is also accepted. |
| `asyncapi_spec_url` | string  | No       | URL to an AsyncAPI spec for WebSocket or SSE documentation (max 2048 chars) |
| `ssh_config`   | object  | No       | Replacement SSH configuration for SSH services (`host`, `port`, `certificate_auth_enabled`, `certificate_ttl_minutes`, `allowed_principals`) |
| `identity_propagation_mode` | string | No | Identity propagation mode: `none` (default), `headers`, `jwt`, or `both` |
| `identity_include_user_id`  | boolean | No | Include `X-NyxID-User-Id` header when propagating identity |
| `identity_include_email`    | boolean | No | Include `X-NyxID-User-Email` header when propagating identity |
| `identity_include_name`     | boolean | No | Include `X-NyxID-User-Name` header when propagating identity |
| `identity_jwt_audience`     | string  | No | Custom JWT `aud` claim for identity assertions (defaults to service `base_url`) |

At least one field must be provided.

```json
{
  "name": "Updated Analytics API",
  "description": "Updated description",
  "base_url": "https://new-analytics.example.com",
  "openapi_spec_url": "https://analytics.example.com/openapi.json",
  "asyncapi_spec_url": "https://analytics.example.com/asyncapi.json"
}
```

**Response (200):**

Returns the full updated service object (same shape as GET response).

When `base_url`, `openapi_spec_url`, or `asyncapi_spec_url` changes on an HTTP service, NyxID re-runs documentation discovery and updates `streaming_supported`.

**Errors:**
- `1002 forbidden` -- User is not admin and not the service creator
- `1003 not_found` -- Service does not exist
- `1008 validation_error` -- Name empty or too long, description too long, base_url too long or SSRF-blocked, spec URL invalid, or no fields provided

**Example:**

```bash
curl -X PUT http://localhost:3001/api/v1/services/d1e2f3a4-b5c6-7890-1234-567890abcdef \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Analytics API"}'
```

---

#### DELETE /api/v1/services/{service_id}

Deactivate a downstream service (soft delete). Only admins or the original service creator can perform this action.

**Auth:** Admin (or service creator)

**Path Parameters:**

| Parameter    | Type | Description    |
|--------------|------|----------------|
| `service_id` | UUID | The service ID |

**Response (200):**

```json
{
  "message": "Service deactivated"
}
```

**Errors:**
- `1002 forbidden` -- User is not admin and not the service creator
- `1003 not_found` -- Service does not exist

**Example:**

```bash
curl -X DELETE http://localhost:3001/api/v1/services/d1e2f3a4-b5c6-7890-1234-567890abcdef \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### GET /api/v1/services/{service_id}/oidc-credentials

Retrieve the OIDC client credentials and discovery endpoints for a service configured with OIDC auth. The client secret is decrypted from storage and returned in plaintext.

**Auth:** Admin

**Path Parameters:**

| Parameter    | Type | Description    |
|--------------|------|----------------|
| `service_id` | UUID | The service ID |

**Response (200):**

```json
{
  "client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "client_secret": "nyx_secret_abc123...",
  "redirect_uris": ["https://portal.example.com/callback"],
  "allowed_scopes": "openid profile email",
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "userinfo_endpoint": "https://auth.example.com/oauth/userinfo",
  "jwks_uri": "https://auth.example.com/.well-known/jwks.json"
}
```

**Errors:**
- `1000 bad_request` -- Service is not an OIDC service
- `1002 forbidden` -- User is not an admin
- `1003 not_found` -- Service does not exist

**Example:**

```bash
curl http://localhost:3001/api/v1/services/d1e2f3a4-b5c6-7890-1234-567890abcdef/oidc-credentials \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### PUT /api/v1/services/{service_id}/redirect-uris

Update the redirect URIs for an OIDC service. Replaces the full set of redirect URIs on the associated OAuth client.

**Auth:** Admin

**Path Parameters:**

| Parameter    | Type | Description    |
|--------------|------|----------------|
| `service_id` | UUID | The service ID |

**Request Body:**

| Field           | Type     | Required | Description                                          |
|-----------------|----------|----------|------------------------------------------------------|
| `redirect_uris` | string[] | Yes      | Array of redirect URIs (1-10 items, max 2048 chars each, http/https only) |

```json
{
  "redirect_uris": [
    "https://portal.example.com/callback",
    "https://portal.example.com/auth/callback"
  ]
}
```

**Response (200):**

```json
{
  "redirect_uris": [
    "https://portal.example.com/callback",
    "https://portal.example.com/auth/callback"
  ]
}
```

**Errors:**
- `1000 bad_request` -- Service is not an OIDC service
- `1002 forbidden` -- User is not an admin
- `1003 not_found` -- Service does not exist
- `1008 validation_error` -- Empty array, more than 10 URIs, URI too long, or invalid URI scheme

**Example:**

```bash
curl -X PUT http://localhost:3001/api/v1/services/d1e2f3a4-b5c6-7890-1234-567890abcdef/redirect-uris \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"redirect_uris": ["https://portal.example.com/callback"]}'
```

---

#### POST /api/v1/services/{service_id}/regenerate-secret

Regenerate the OIDC client secret for a service. The previous secret is immediately invalidated. Store the new secret securely -- it cannot be retrieved again.

**Auth:** Admin

**Path Parameters:**

| Parameter    | Type | Description    |
|--------------|------|----------------|
| `service_id` | UUID | The service ID |

**Response (200):**

```json
{
  "client_secret": "nyx_secret_new_abc123...",
  "message": "Previous secret is now invalidated. Store this secret securely."
}
```

**Errors:**
- `1000 bad_request` -- Service is not an OIDC service
- `1002 forbidden` -- User is not an admin
- `1003 not_found` -- Service does not exist

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/services/d1e2f3a4-b5c6-7890-1234-567890abcdef/regenerate-secret \
  -H "Authorization: Bearer <admin_access_token>"
```

---

### SSH

NyxID supports authenticated SSH-over-WebSocket tunnels plus short-lived SSH certificate issuance for downstream services.

SSH configuration is embedded directly in the service object under `ssh_config` when `service_type` is `"ssh"`. Create SSH services with `POST /api/v1/services` and update them with `PUT /api/v1/services/{service_id}` instead of calling separate SSH-specific CRUD endpoints.

#### POST /api/v1/ssh/{service_id}/certificate

Issue a short-lived OpenSSH user certificate for the authenticated caller.

**Auth:** Required

**Request Body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `public_key` | string | Yes | OpenSSH public key to sign |
| `principal` | string | Yes | SSH principal to embed in the certificate |

**Response (200):**

```json
{
  "service_id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
  "key_id": "d1e2f3a4-b5c6-7890-1234-567890abcdef:user-1:ubuntu:1742292000",
  "principal": "ubuntu",
  "certificate": "ssh-ed25519-cert-v01@openssh.com AAAAI...",
  "ca_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...",
  "valid_after": "2026-03-18T10:20:00+00:00",
  "valid_before": "2026-03-18T10:50:00+00:00"
}
```

#### GET /api/v1/ssh/{service_id}

Upgrade the request to WebSocket and carry raw SSH TCP payloads over binary frames. This endpoint is intended for the built-in `nyxid ssh proxy` helper and OpenSSH `ProxyCommand` integration rather than direct browser use.

**Auth:** Required

**Response:** `101 Switching Protocols`

For full operator setup, certificate trust, and `ProxyCommand` examples, see [SSH_TUNNELING.md](./SSH_TUNNELING.md).

---

### Service Endpoints

Endpoints describe the individual API operations available on a downstream service. They are used by the MCP proxy to generate MCP tools, and can be created manually or auto-discovered from an OpenAPI spec.

Endpoint names must match `^[a-z][a-z0-9_]*$` (valid MCP tool names).

#### GET /api/v1/services/{service_id}/endpoints

List all active endpoints for a service.

**Auth:** Required

**Path Parameters:**

| Parameter    | Type | Description    |
|--------------|------|----------------|
| `service_id` | UUID | The service ID |

**Response (200):**

```json
{
  "endpoints": [
    {
      "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
      "service_id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
      "name": "list_customers",
      "description": "List all customers with pagination",
      "method": "GET",
      "path": "/v1/customers",
      "parameters": [
        {"name": "limit", "in": "query", "schema": {"type": "integer"}}
      ],
      "request_body_schema": null,
      "response_description": null,
      "response": {
        "content_types": ["application/json"],
        "binary_artifact": false
      },
      "is_active": true,
      "created_at": "2025-06-01T10:00:00+00:00",
      "updated_at": "2025-06-01T10:00:00+00:00"
    }
  ]
}
```

**Errors:**
- `1003 not_found` -- Service does not exist

**Example:**

```bash
curl http://localhost:3001/api/v1/services/d1e2f3a4-b5c6-7890-1234-567890abcdef/endpoints \
  -H "Authorization: Bearer <access_token>"
```

---

#### POST /api/v1/services/{service_id}/endpoints

Create a new endpoint for a service.

**Auth:** Admin (or service creator)

**Path Parameters:**

| Parameter    | Type | Description    |
|--------------|------|----------------|
| `service_id` | UUID | The service ID |

**Request Body:**

| Field                  | Type   | Required | Description                                        |
|------------------------|--------|----------|----------------------------------------------------|
| `name`                 | string | Yes      | MCP tool name (1-100 chars, `^[a-z][a-z0-9_]*$`)  |
| `description`          | string | No       | Human-readable description                         |
| `method`               | string | Yes      | HTTP method: GET, POST, PUT, DELETE, PATCH         |
| `path`                 | string | Yes      | URL path starting with `/` (max 2048 chars)        |
| `parameters`           | JSON   | No       | OpenAPI-style parameter definitions                |
| `request_body_schema`  | JSON   | No       | JSON Schema for the request body                   |
| `response_description` | string | No       | Description of the expected response               |
| `response`             | object | No       | Typed success response: `content_types` plus tri-state `binary_artifact` |

```json
{
  "name": "list_customers",
  "description": "List all customers with pagination",
  "method": "GET",
  "path": "/v1/customers",
  "parameters": [
    {"name": "limit", "in": "query", "schema": {"type": "integer"}},
    {"name": "offset", "in": "query", "schema": {"type": "integer"}}
  ]
}
```

**Response (200):**

Returns the created endpoint object (same shape as list response items).

**Errors:**
- `1002 forbidden` -- User is not admin and not the service creator
- `1003 not_found` -- Service does not exist
- `1008 validation_error` -- Invalid name format, unsupported method, or path not starting with `/`
- `1007 database_error` -- Duplicate endpoint name for this service (unique constraint)

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/services/d1e2f3a4-b5c6-7890-1234-567890abcdef/endpoints \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "list_customers",
    "method": "GET",
    "path": "/v1/customers"
  }'
```

---

#### PUT /api/v1/services/{service_id}/endpoints/{endpoint_id}

Update an existing endpoint. Only the provided fields are updated (partial update).

**Auth:** Admin (or service creator)

**Path Parameters:**

| Parameter     | Type | Description      |
|---------------|------|------------------|
| `service_id`  | UUID | The service ID   |
| `endpoint_id` | UUID | The endpoint ID  |

**Request Body:**

| Field                  | Type    | Required | Description                                              |
|------------------------|---------|----------|----------------------------------------------------------|
| `name`                 | string  | No       | MCP tool name (1-100 chars, `^[a-z][a-z0-9_]*$`)        |
| `description`          | string? | No       | Human-readable description (null to clear)               |
| `method`               | string  | No       | HTTP method: GET, POST, PUT, DELETE, PATCH               |
| `path`                 | string  | No       | URL path starting with `/` (max 2048 chars)              |
| `parameters`           | JSON?   | No       | OpenAPI-style parameter definitions (null to clear)      |
| `request_body_schema`  | JSON?   | No       | JSON Schema for the request body (null to clear)         |
| `response_description` | string? | No       | Description of the expected response (null to clear)     |
| `response`             | object  | No       | Replacement typed success response contract              |
| `is_active`            | boolean | No       | Enable or disable the endpoint                           |

**Response (200):**

```json
{
  "message": "Endpoint updated"
}
```

**Errors:**
- `1002 forbidden` -- User is not admin and not the service creator
- `1003 not_found` -- Service or endpoint does not exist
- `1008 validation_error` -- Invalid name, method, or path

**Example:**

```bash
curl -X PUT http://localhost:3001/api/v1/services/d1e2f3a4-b5c6-7890-1234-567890abcdef/endpoints/e1f2a3b4-c5d6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description", "is_active": false}'
```

---

#### DELETE /api/v1/services/{service_id}/endpoints/{endpoint_id}

Permanently delete an endpoint.

**Auth:** Admin (or service creator)

**Path Parameters:**

| Parameter     | Type | Description      |
|---------------|------|------------------|
| `service_id`  | UUID | The service ID   |
| `endpoint_id` | UUID | The endpoint ID  |

**Response (200):**

```json
{
  "message": "Endpoint deleted"
}
```

**Errors:**
- `1002 forbidden` -- User is not admin and not the service creator
- `1003 not_found` -- Service or endpoint does not exist

**Example:**

```bash
curl -X DELETE http://localhost:3001/api/v1/services/d1e2f3a4-b5c6-7890-1234-567890abcdef/endpoints/e1f2a3b4-c5d6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### POST /api/v1/services/{service_id}/discover-endpoints

Fetch the service's `openapi_spec_url` (or legacy `api_spec_url` alias), parse the OpenAPI/Swagger specification, and bulk upsert discovered endpoints. Existing endpoints matched by name are updated; new ones are created; endpoints not in the spec are soft-deleted (set `is_active = false`).

**Auth:** Admin (or service creator)

**Path Parameters:**

| Parameter    | Type | Description    |
|--------------|------|----------------|
| `service_id` | UUID | The service ID |

**Prerequisites:** The service must have `openapi_spec_url` set (via `PUT /api/v1/services/{service_id}`).

**Supported Specs:** OpenAPI 3.x and Swagger 2.0 in JSON format.

**Response (200):**

```json
{
  "message": "12 endpoints discovered and synced",
  "endpoints": [
    {
      "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
      "service_id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
      "name": "list_customers",
      "description": "List all customers",
      "method": "GET",
      "path": "/v1/customers",
      "parameters": [...],
      "request_body_schema": null,
      "response_description": null,
      "response": {
        "content_types": ["application/json"],
        "binary_artifact": false
      },
      "is_active": true,
      "created_at": "2025-06-01T10:00:00+00:00",
      "updated_at": "2025-06-01T12:00:00+00:00"
    }
  ]
}
```

**Errors:**
- `1000 bad_request` -- Service has no `openapi_spec_url`, spec fetch failed, invalid spec format, or spec is not JSON
- `1002 forbidden` -- User is not admin and not the service creator
- `1003 not_found` -- Service does not exist

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/services/d1e2f3a4-b5c6-7890-1234-567890abcdef/discover-endpoints \
  -H "Authorization: Bearer <admin_access_token>"
```

---

### MCP Config

#### GET /api/v1/mcp/config

Returns the stable, caller-specific MCP operation catalog contract. NyxID is the authority for OpenAPI parsing, credential availability, node routing availability, and service/node authorization scope. Consumers must map this normalized catalog into their own types and must not fetch the raw downstream OpenAPI document again.

Contract guarantees for `contract_version: "1.0"`:

- For `is_user_service: true`, `service_id` is the exact `UserService.id` used by proxy authorization. Platform catalog services use the exact `DownstreamService.id` and set `is_user_service: false`.
- `endpoint_id` is a stable, service-local, opaque operation identity. Persisted catalog operations use their stored endpoint UUID. Custom OpenAPI identities remain stable while the source `operationId` remains stable; when it is absent, stability follows the source method/path pair. The generic proxy has its own reserved identity. These generation details are producer semantics only: consumers must not reconstruct or interpret an ID from `name`, `method`, or `path`.
- Missing or duplicate service identities, or missing/duplicate endpoint identities within one service, fail the request closed. An ambiguous catalog is never published.
- `is_generic_proxy: true` means the service exposes only NyxID's generic HTTP request operation. It is not a declared OpenAPI operation and must not be admitted as one.
- Only currently executable operations are in `services`. Credential-unavailable services are counted in diagnostics but omitted. Service and node scope restrictions are applied before publication.
- `service_scope_restricted` and `node_scope_restricted` report that caller scope is active. `node_scope_exclusions_present` may explain an omission only after service authorization has established that the service is caller-visible; it is a boolean and never enumerates excluded nodes or services. Diagnostics never include excluded-resource counts, IDs, node topology, credential material, tokens, or internal routing details.
- REST `/mcp/config` and stateless MCP `tools/list` use the same scoped catalog loader, including auto-connected service expansion. Assistant chat keys discover services before acknowledgement on both surfaces; platform grants and account acknowledgement gate execution, not discovery. MCP adds its protocol-specific account/meta-tools separately. Stateful MCP sessions may show only the subset activated for that session.

`catalog_digest` is the source revision for the normalized descriptor. It is `sha256:<lowercase-hex>` over compact UTF-8 JSON containing exactly `{"contract_version":"1.0","services":[...]}`. Services are sorted by `service_id`, endpoints by `endpoint_id`, and every JSON object key recursively in lexicographic order. `user_id`, `proxy_base_url`, diagnostics, counts, and observation time are excluded. Consumers must not substitute fetch time or a local counter for this digest.

Schema contract:

- `parameters` is either `null` or an OpenAPI parameter array. Supported locations are `path`, `query`, `header`, and `cookie`; each entry expresses requiredness with `required: true`. A required caller-supplied header is therefore an entry with `in: "header"` and `required: true`.
- Parameter schemas guarantee the `type`, `description`, `format`, `enum`, and `default` keywords.
- Request bodies use `json-schema-subset-v1`; the guaranteed keywords are listed in `schema_contract.request_body_schema_keywords`. Local `$ref` values are expanded by NyxID. Consumers must fail closed on an operation that requires unsupported schema behavior.
- Headers listed in `schema_contract.managed_headers`, and names beginning with a listed `managed_header_prefixes` value, are managed by NyxID and cannot be supplied as MCP arguments.
- `response.content_types` contains normalized declared success media types. `response.binary_artifact` is `true` for a declared binary/file response, `false` for a classifiable non-binary response, and `null` when the source contract is insufficient. Consumers requiring a binary artifact must admit only `true`.

Platform services are included only when the user has a valid connection with satisfied credentials. `provider` services are excluded because they are not proxyable. User-managed services additionally require an executable server credential or an in-scope dispatchable node route.

**Auth:** Session cookie, human access token, general `nyx_` or scoped/platform `nyxid_ag_` API key (via `X-API-Key` or `Authorization: Bearer`), or non-Curation service-account access token. Tokens and API keys require `proxy` or `proxy:*` scope. Scheduled-invocation keys, Curation service accounts, delegated tokens, and relay tokens are rejected.

**Response (200):**

```json
{
  "contract_version": "1.0",
  "catalog_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "proxy_base_url": "https://auth.example.com/api/v1/proxy",
  "schema_contract": {
    "parameters_format": "openapi-parameter-array-v1",
    "parameter_locations": ["path", "query", "header", "cookie"],
    "parameter_schema_keywords": ["type", "description", "format", "enum", "default"],
    "request_body_schema_format": "json-schema-subset-v1",
    "request_body_schema_keywords": ["type", "properties", "required", "items", "additionalProperties", "description", "format", "enum", "default", "minimum", "maximum", "minLength", "maxLength", "allOf", "anyOf", "oneOf"],
    "required_headers": "parameters entries with in=header and required=true",
    "managed_headers": ["host", "authorization", "cookie", "set-cookie", "transfer-encoding", "content-length", "connection", "x-forwarded-for", "x-forwarded-host", "x-real-ip", "content-type", "accept"],
    "managed_header_prefixes": ["x-nyxid-"]
  },
  "services": [
    {
      "service_id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
      "service_name": "Stripe API",
      "service_slug": "stripe",
      "description": "Payment processing",
      "service_category": "connection",
      "is_user_service": false,
      "is_generic_proxy": false,
      "endpoints": [
        {
          "endpoint_id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
          "name": "list_customers",
          "description": "List all customers with pagination",
          "method": "GET",
          "path": "/v1/customers",
          "parameters": [
            {"name": "limit", "in": "query", "schema": {"type": "integer"}}
          ],
          "request_body_schema": null,
          "request_content_type": null,
          "request_body_required": false,
          "response_description": null,
          "response": {
            "content_types": ["application/json"],
            "binary_artifact": false
          }
        }
      ]
    }
  ],
  "total_services": 1,
  "total_endpoints": 1,
  "diagnostics": {
    "no_visible_connections": false,
    "unavailable_services": 0,
    "generic_only_services": 0,
    "invalid_contract_services": 0,
    "service_scope_restricted": false,
    "node_scope_restricted": false,
    "node_scope_exclusions_present": false
  }
}
```

If the caller has no visible connections, `services` is empty, counts are `0`, and `diagnostics.no_visible_connections` is `true`. Other typed diagnostics distinguish visible-but-unavailable credentials/routes, generic-only fallback, and invalid visible operation contracts without exposing secrets or authorization-excluded resources.

**Example:**

```bash
curl http://localhost:3001/api/v1/mcp/config \
  -H "Authorization: Bearer <access_token>"
```

---

### Service Connections

Connections allow individual users to associate themselves with downstream services. Services are divided into three categories:

- **provider** -- OIDC/SSO services where NyxID is the identity provider. Not user-connectable.
- **connection** -- External services that require per-user credentials (API keys, bearer tokens, basic auth).
- **internal** -- Services that use a master credential managed by the admin. Users just "enable" access.

When proxying requests, `connection` services use the per-user encrypted credential. `internal` services use the service-level master credential but require an active connection record.

#### GET /api/v1/connections

List all active service connections for the authenticated user.

**Auth:** Required

**Response (200):**

```json
{
  "connections": [
    {
      "service_id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
      "service_name": "Stripe API",
      "service_category": "connection",
      "auth_type": "api_key",
      "has_credential": true,
      "credential_label": "Production Key",
      "connected_at": "2025-06-01T10:00:00+00:00"
    },
    {
      "service_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "service_name": "Internal Analytics",
      "service_category": "internal",
      "auth_type": "bearer",
      "has_credential": false,
      "credential_label": null,
      "connected_at": "2025-06-01T10:00:00+00:00"
    }
  ]
}
```

**Example:**

```bash
curl http://localhost:3001/api/v1/connections \
  -H "Authorization: Bearer <access_token>"
```

---

#### POST /api/v1/connections/{service_id}

Connect the authenticated user to a downstream service. For `connection` category services, a credential must be provided in the JSON body. For `internal` services, no credential is needed (omit `credential` or set to `null`). Provider services cannot be connected to.

**Auth:** Required

**Path Parameters:**

| Parameter    | Type | Description    |
|--------------|------|----------------|
| `service_id` | UUID | The service ID |

**Request Body:**

| Field              | Type   | Required | Description                                           |
|--------------------|--------|----------|-------------------------------------------------------|
| `credential`       | string | Depends  | Required for `connection` services. Must be absent/null for `internal` services. Max 8192 chars. |
| `credential_label` | string | No       | Optional label (e.g., "Production Key"). Max 200 chars. |

**Example (connection service):**

```json
{
  "credential": "sk-live-abc123...",
  "credential_label": "Production Key"
}
```

**Example (internal service):**

```json
{}
```

**Response (200):**

```json
{
  "service_id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
  "service_name": "Stripe API",
  "connected_at": "2025-06-01T10:00:00+00:00"
}
```

**Errors:**
- `1000 bad_request` -- Provider services are not connectable, or credential missing/unexpected for the service category
- `1003 not_found` -- Service does not exist or is inactive
- `1004 conflict` -- Already connected to this service
- `1008 validation_error` -- Credential empty, too long, or label too long

**Example:**

```bash
# Connect to a "connection" service with credentials
curl -X POST http://localhost:3001/api/v1/connections/d1e2f3a4-b5c6-7890-1234-567890abcdef \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"credential": "sk-live-abc123", "credential_label": "Production Key"}'

# Connect to an "internal" service (no credential)
curl -X POST http://localhost:3001/api/v1/connections/a1b2c3d4-e5f6-7890-1234-567890abcdef \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

---

#### PUT /api/v1/connections/{service_id}/credential

Update the credential on an existing connection. Only applicable to `connection` category services (those that require per-user credentials).

**Auth:** Required

**Path Parameters:**

| Parameter    | Type | Description    |
|--------------|------|----------------|
| `service_id` | UUID | The service ID |

**Request Body:**

| Field              | Type   | Required | Description                                  |
|--------------------|--------|----------|----------------------------------------------|
| `credential`       | string | Yes      | New credential value. Max 8192 chars.        |
| `credential_label` | string | No       | New label. When omitted, existing label is preserved. Max 200 chars. |

```json
{
  "credential": "sk-live-new-key-456...",
  "credential_label": "Rotated Production Key"
}
```

**Response (200):**

```json
{
  "message": "Credential updated"
}
```

**Errors:**
- `1000 bad_request` -- Service does not use per-user credentials
- `1003 not_found` -- No active connection found for this service
- `1008 validation_error` -- Credential empty, too long, or label too long

**Example:**

```bash
curl -X PUT http://localhost:3001/api/v1/connections/d1e2f3a4-b5c6-7890-1234-567890abcdef/credential \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"credential": "sk-live-new-key-456"}'
```

---

#### DELETE /api/v1/connections/{service_id}

Disconnect the authenticated user from a downstream service. Securely clears all stored credential data (encrypted credential, credential type, credential label).

**Auth:** Required

**Path Parameters:**

| Parameter    | Type | Description    |
|--------------|------|----------------|
| `service_id` | UUID | The service ID |

**Response (200):**

```json
{
  "message": "Disconnected from service"
}
```

**Errors:**
- `1003 not_found` -- Connection does not exist

**Example:**

```bash
curl -X DELETE http://localhost:3001/api/v1/connections/d1e2f3a4-b5c6-7890-1234-567890abcdef \
  -H "Authorization: Bearer <access_token>"
```

---

### Service Provider Requirements

Service provider requirements define which external providers (e.g., OpenAI, Anthropic) a downstream service needs credentials from. When a user proxies a request to that service, NyxID resolves the user's provider tokens and injects them into the outbound request alongside the service credential.

#### GET /api/v1/services/{service_id}/requirements

List all provider requirements for a service.

**Auth:** Required

**Path Parameters:**

| Parameter    | Type | Description    |
|--------------|------|----------------|
| `service_id` | UUID | The service ID |

**Response (200):**

```json
{
  "requirements": [
    {
      "id": "r1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "service_id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
      "provider_config_id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "provider_name": "OpenAI",
      "provider_slug": "openai",
      "required": true,
      "scopes": null,
      "injection_method": "bearer",
      "injection_key": null,
      "created_at": "2025-06-01T10:00:00+00:00",
      "updated_at": "2025-06-01T10:00:00+00:00"
    }
  ]
}
```

**Errors:**
- `1003 not_found` -- Service does not exist

**Example:**

```bash
curl http://localhost:3001/api/v1/services/d1e2f3a4-b5c6-7890-1234-567890abcdef/requirements \
  -H "Authorization: Bearer <access_token>"
```

---

#### POST /api/v1/services/{service_id}/requirements

Add a provider requirement to a service. The proxy will inject the user's token for this provider into outbound requests.

**Auth:** Admin

**Path Parameters:**

| Parameter    | Type | Description    |
|--------------|------|----------------|
| `service_id` | UUID | The service ID |

**Request Body:**

| Field                | Type     | Required | Description                                                              |
|----------------------|----------|----------|--------------------------------------------------------------------------|
| `provider_config_id` | string   | Yes      | ID of the provider configuration                                         |
| `required`           | boolean  | Yes      | If `true`, proxy fails when user has no token for this provider          |
| `scopes`             | string[] | No       | Specific OAuth scopes this service needs from the provider               |
| `injection_method`   | string   | Yes      | How to inject the token: `bearer`, `header`, or `query`                  |
| `injection_key`      | string   | No       | Header name or query param. Defaults: `Authorization` (bearer), `X-API-Key` (header), `api_key` (query) |

**Injection Method Defaults:**

| `injection_method` | Default `injection_key` | Behavior                              |
|---------------------|-------------------------|---------------------------------------|
| `bearer`            | `Authorization`         | Adds `Authorization: Bearer <token>`  |
| `header`            | `X-API-Key`             | Adds `<injection_key>: <token>`       |
| `query`             | `api_key`               | Appends `?<injection_key>=<token>`    |

**Blocked Injection Keys:** The following header names are blocked for security: `host`, `authorization`, `cookie`, `set-cookie`, `transfer-encoding`, `content-length`, `connection`, `x-forwarded-for`, `x-forwarded-host`, `x-real-ip`.

```json
{
  "provider_config_id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "required": true,
  "injection_method": "bearer"
}
```

**Response (200):**

Returns the created requirement with provider details.

**Errors:**
- `1002 forbidden` -- User is not an admin
- `1003 not_found` -- Service or provider does not exist
- `1004 conflict` -- This provider requirement already exists for this service
- `1008 validation_error` -- Invalid injection_method or blocked injection_key

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/services/d1e2f3a4-b5c6-7890-1234-567890abcdef/requirements \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_config_id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "required": true,
    "injection_method": "bearer"
  }'
```

---

#### DELETE /api/v1/services/{service_id}/requirements/{requirement_id}

Remove a provider requirement from a service.

**Auth:** Admin

**Path Parameters:**

| Parameter        | Type | Description         |
|------------------|------|---------------------|
| `service_id`     | UUID | The service ID      |
| `requirement_id` | UUID | The requirement ID  |

**Response (200):**

```json
{
  "message": "Requirement removed"
}
```

**Errors:**
- `1002 forbidden` -- User is not an admin
- `1003 not_found` -- Requirement does not exist

**Example:**

```bash
curl -X DELETE http://localhost:3001/api/v1/services/d1e2f3a4-b5c6-7890-1234-567890abcdef/requirements/r1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <admin_access_token>"
```

---

### Providers

Providers represent external service providers that users can connect their credentials to. NyxID seeds 19 providers at startup: API key providers (OpenAI, Anthropic, Google AI, Mistral, Cohere, DeepSeek), OAuth2 providers (Google, GitHub, Twitter/X, Facebook, Discord, Spotify, LinkedIn, Slack, Microsoft, TikTok, Twitch, Reddit), and device-code providers (OpenAI Codex). Users connect by entering API keys, completing OAuth2 flows, or using device-code authorization. Providers support three credential modes: `admin` (admin-configured OAuth app), `user` (users bring their own OAuth app credentials), or `both`.

#### GET /api/v1/providers

List all active provider configurations.

**Auth:** Required

**Response (200):**

```json
{
  "providers": [
    {
      "id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "slug": "openai",
      "name": "OpenAI",
      "description": "OpenAI API for GPT models",
      "provider_type": "api_key",
      "credential_mode": "admin",
      "revocation": null,
      "has_oauth_config": false,
      "default_scopes": null,
      "supports_pkce": false,
      "token_endpoint_auth_method": "client_secret_post",
      "extra_auth_params": null,
      "device_code_format": "rfc8628",
      "client_id_param_name": null,
      "api_key_instructions": "Get your API key from https://platform.openai.com/api-keys",
      "api_key_url": "https://platform.openai.com/api-keys",
      "icon_url": "https://example.com/openai-icon.svg",
      "documentation_url": "https://platform.openai.com/docs",
      "is_active": true,
      "created_at": "2025-06-01T10:00:00+00:00",
      "updated_at": "2025-06-01T10:00:00+00:00"
    }
  ]
}
```

**Example:**

```bash
curl http://localhost:3001/api/v1/providers \
  -H "Authorization: Bearer <access_token>"
```

---

#### POST /api/v1/providers

Register a new provider configuration. OAuth2 providers require additional fields for the OAuth flow.

**Auth:** Admin

**Request Body:**

| Field               | Type     | Required | Description                                                          |
|---------------------|----------|----------|----------------------------------------------------------------------|
| `name`              | string   | Yes      | Display name (max 200 chars)                                         |
| `slug`              | string   | Yes      | URL-safe identifier (1-100 chars, lowercase alphanumeric + hyphens)  |
| `description`       | string   | No       | Provider description                                                 |
| `provider_type`     | string   | Yes      | `oauth2`, `api_key`, or `device_code`                                |
| `credential_mode`   | string   | No       | `admin` (default), `user`, or `both` -- controls where OAuth client credentials come from during setup. **Only applies to `oauth2` and `device_code` providers.** For `api_key` providers, must be `admin` or omitted (the API rejects other values). Does not affect request-time credential resolution for any provider type. |
| `authorization_url` | string   | OAuth2   | OAuth2 authorization endpoint (required for `oauth2` type)           |
| `token_url`         | string   | OAuth2   | OAuth2 token endpoint (required for `oauth2` type)                   |
| `revocation`        | object   | No       | Structured upstream revocation configuration for `oauth2`/`device_code`; see below |
| `revocation_url`    | string   | No       | Deprecated RFC 7009 alias; mapped to `revocation` when the structured field is omitted |
| `default_scopes`    | string[] | No       | Default OAuth2 scopes to request                                     |
| `client_id`         | string   | OAuth2   | OAuth2 client ID (required for `oauth2` type, encrypted at rest)     |
| `client_secret`     | string   | OAuth2   | OAuth2 client secret (required for `oauth2` type, encrypted at rest) |
| `supports_pkce`     | boolean  | No       | Whether the provider supports PKCE (default: `false`)                |
| `token_endpoint_auth_method` | string | No | `client_secret_post` (default) or `client_secret_basic`             |
| `extra_auth_params` | object   | No       | Extra authorization URL parameters (e.g., `{"access_type": "offline"}`) |
| `device_code_url`   | string   | device_code | Device authorization endpoint (required for `device_code` type)   |
| `device_token_url`  | string   | device_code | Device token polling endpoint (required for `device_code` type)   |
| `device_verification_url` | string | No   | User verification URL for device code flow                           |
| `device_code_format` | string  | No       | `rfc8628` (default) or `openai`                                      |
| `client_id_param_name` | string | No      | Custom client_id parameter name (e.g., `client_key` for TikTok)     |
| `api_key_instructions` | string | No      | Instructions for obtaining an API key (for `api_key` type)           |
| `api_key_url`       | string   | No       | URL where users can create API keys                                  |
| `icon_url`          | string   | No       | Provider icon/logo URL                                               |
| `documentation_url` | string   | No       | Provider documentation URL                                           |

**Slug Validation:** Must contain only lowercase letters, digits, and hyphens. No leading, trailing, or consecutive hyphens.

`revocation` contains `style` (`rfc7009`, `github`, `self_bearer`, or `facebook_deauth`), an HTTPS public `url` without userinfo, `auth` (`inherit`, `none`, `client_id`, `basic`, or `post`), and `revokes_grant` (boolean). Structured `revocation` wins if both it and deprecated `revocation_url` are supplied. Revocation configuration is rejected for `api_key` and `telegram_widget` providers.

**Example (API key provider):**

```json
{
  "name": "OpenAI",
  "slug": "openai",
  "description": "OpenAI API for GPT models",
  "provider_type": "api_key",
  "api_key_instructions": "Get your API key from https://platform.openai.com/api-keys",
  "api_key_url": "https://platform.openai.com/api-keys",
  "icon_url": "https://example.com/openai-icon.svg",
  "documentation_url": "https://platform.openai.com/docs"
}
```

**Example (OAuth2 provider):**

```json
{
  "name": "Google AI",
  "slug": "google-ai",
  "provider_type": "oauth2",
  "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth",
  "token_url": "https://oauth2.googleapis.com/token",
  "revocation": {
    "style": "rfc7009",
    "url": "https://oauth2.googleapis.com/revoke",
    "auth": "none",
    "revokes_grant": false
  },
  "default_scopes": ["https://www.googleapis.com/auth/generative-language"],
  "client_id": "your-client-id.apps.googleusercontent.com",
  "client_secret": "your-client-secret",
  "supports_pkce": true
}
```

**Response (200):**

Returns the created provider (same shape as list response items, without encrypted fields).

**Errors:**
- `1002 forbidden` -- User is not an admin
- `1004 conflict` -- Slug already exists
- `1008 validation_error` -- Missing required fields, invalid provider_type/credential_mode, invalid slug, or SSRF-blocked URL

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/providers \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenAI",
    "slug": "openai",
    "provider_type": "api_key",
    "api_key_url": "https://platform.openai.com/api-keys"
  }'
```

---

#### GET /api/v1/providers/{provider_id}

Get a single provider configuration by ID.

**Auth:** Required

**Path Parameters:**

| Parameter     | Type | Description     |
|---------------|------|-----------------|
| `provider_id` | UUID | The provider ID |

**Response (200):**

Returns a single provider object (same shape as list response items).

Provider responses include the saved `authorization_url`, `token_url`, and
`revocation_url`, plus `has_client_id` and `has_client_secret` booleans. These
allow editors to display configured values without returning stored client
credentials. Device-flow URLs remain available in their corresponding fields.

**Errors:**
- `1003 not_found` -- Provider does not exist

**Example:**

```bash
curl http://localhost:3001/api/v1/providers/p1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <access_token>"
```

---

#### PUT /api/v1/providers/{provider_id}

Update a provider configuration. Only the provided fields are updated (partial update).

**Auth:** Admin

**Path Parameters:**

| Parameter     | Type | Description     |
|---------------|------|-----------------|
| `provider_id` | UUID | The provider ID |

**Request Body:**

| Field               | Type     | Required | Description                                          |
|---------------------|----------|----------|------------------------------------------------------|
| `name`              | string   | No       | Display name                                         |
| `description`       | string   | No       | Provider description                                 |
| `is_active`         | boolean  | No       | Enable or disable the provider                       |
| `credential_mode`   | string   | No       | `admin`, `user`, or `both` (oauth2/device_code only; must be `admin` for api_key) |
| `authorization_url` | string   | No       | OAuth2 authorization endpoint                        |
| `token_url`         | string   | No       | OAuth2 token endpoint                                |
| `revocation`        | object/null | No    | Structured upstream revocation configuration; `null` explicitly clears it and its legacy alias |
| `revocation_url`    | string   | No       | Deprecated RFC 7009 alias; mapped to `revocation` when the structured field is omitted |
| `default_scopes`    | string[] | No       | Default OAuth2 scopes                                |
| `client_id`         | string   | No       | OAuth2 client ID (encrypted at rest)                 |
| `client_secret`     | string   | No       | OAuth2 client secret (encrypted at rest)             |
| `supports_pkce`     | boolean  | No       | PKCE support flag                                    |
| `token_endpoint_auth_method` | string | No | `client_secret_post` or `client_secret_basic`       |
| `extra_auth_params` | object   | No       | Extra authorization URL parameters                   |
| `device_code_url`   | string   | No       | Device authorization endpoint                        |
| `device_token_url`  | string   | No       | Device token polling endpoint                        |
| `device_verification_url` | string | No   | User verification URL for device code flow           |
| `device_code_format` | string  | No       | `rfc8628` or `openai`                                |
| `client_id_param_name` | string | No      | Custom client_id parameter name                      |
| `api_key_instructions` | string | No      | Instructions for obtaining an API key                |
| `api_key_url`       | string   | No       | URL where users can create API keys                  |
| `icon_url`          | string   | No       | Provider icon/logo URL                               |
| `documentation_url` | string   | No       | Provider documentation URL                           |

**Response (200):**

Returns the updated provider object.

Structured `revocation` uses the same fields and validation rules as provider creation. An omitted field preserves the current configuration; explicit `"revocation": null` clears both `revocation` and deprecated `revocation_url`. RFC 7009 configurations keep the alias synchronized, while vendor-specific styles clear the alias.

An explicit empty `default_scopes` array clears the scope list. Trimmed-empty
`description`, `api_key_instructions`, `api_key_url`, `icon_url`, and
`documentation_url` strings remove the corresponding optional stored field.
Blank replacement credentials should be omitted to preserve existing secrets.

**Errors:**
- `1002 forbidden` -- User is not an admin
- `1003 not_found` -- Provider does not exist
- `1008 validation_error` -- SSRF-blocked URL

**Example:**

```bash
curl -X PUT http://localhost:3001/api/v1/providers/p1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description", "is_active": true}'
```

---

#### DELETE /api/v1/providers/{provider_id}

Deactivate a provider and revoke all user tokens associated with it.

**Auth:** Admin

**Path Parameters:**

| Parameter     | Type | Description     |
|---------------|------|-----------------|
| `provider_id` | UUID | The provider ID |

**Response (200):**

```json
{
  "message": "Provider deactivated and user tokens revoked"
}
```

**Errors:**
- `1002 forbidden` -- User is not an admin
- `1003 not_found` -- Provider does not exist

**Example:**

```bash
curl -X DELETE http://localhost:3001/api/v1/providers/p1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <admin_access_token>"
```

---

### User Provider Credentials

Per-user OAuth app credentials for providers configured with `credential_mode` of `"user"` or `"both"`. Users bring their own OAuth client_id and client_secret.

#### GET /api/v1/providers/{provider_id}/credentials

Get the current user's OAuth app credentials metadata for a provider.

**Auth:** Required

**Path Parameters:**

| Parameter     | Type | Description     |
|---------------|------|-----------------|
| `provider_id` | UUID | The provider ID |

**Response (200) -- credentials exist:**

```json
{
  "provider_config_id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "has_credentials": true,
  "label": "My Twitter App",
  "created_at": "2026-03-09T10:00:00+00:00",
  "updated_at": "2026-03-09T10:00:00+00:00"
}
```

**Response (200) -- no credentials:**

```json
{
  "provider_config_id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "has_credentials": false,
  "label": null,
  "created_at": null,
  "updated_at": null
}
```

**Errors:**
- `1003 not_found` -- Provider does not exist
- `1008 validation_error` -- Provider does not support user credentials

**Example:**

```bash
curl http://localhost:3001/api/v1/providers/p1a2b3c4-d5e6-7890-abcd-ef1234567890/credentials \
  -H "Authorization: Bearer <access_token>"
```

---

#### PUT /api/v1/providers/{provider_id}/credentials

Set or update the current user's OAuth app credentials for a provider.

**Auth:** Required

**Path Parameters:**

| Parameter     | Type | Description     |
|---------------|------|-----------------|
| `provider_id` | UUID | The provider ID |

**Request Body:**

| Field           | Type   | Required | Description                                           |
|-----------------|--------|----------|-------------------------------------------------------|
| `client_id`     | string | Yes      | OAuth client ID (max 500 chars, encrypted at rest)    |
| `client_secret` | string | No       | OAuth client secret (max 2000 chars, encrypted at rest) |
| `label`         | string | No       | Display label (max 200 chars)                         |

**Response (200):**

Same as GET response with `has_credentials: true`.

**Errors:**
- `1008 validation_error` -- Provider does not support user credentials, or invalid input

**Example:**

```bash
curl -X PUT http://localhost:3001/api/v1/providers/p1a2b3c4-d5e6-7890-abcd-ef1234567890/credentials \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "my-app-client-id", "client_secret": "my-app-secret", "label": "My Twitter App"}'
```

---

#### DELETE /api/v1/providers/{provider_id}/credentials

Delete the current user's OAuth app credentials for a provider.

**Auth:** Required

**Path Parameters:**

| Parameter     | Type | Description     |
|---------------|------|-----------------|
| `provider_id` | UUID | The provider ID |

**Response (200):**

```json
{
  "message": "Credentials deleted"
}
```

**Errors:**
- `1003 not_found` -- Provider does not exist or no credentials found

**Example:**

```bash
curl -X DELETE http://localhost:3001/api/v1/providers/p1a2b3c4-d5e6-7890-abcd-ef1234567890/credentials \
  -H "Authorization: Bearer <access_token>"
```

---

### User Provider Tokens

#### Codex API-Key Connection

`GET /api/v1/providers/codex-connection` returns the authenticated account,
`openai` provider, nullable connection `{id,state_version}`, nullable `service_id`,
`feature: "openai_responses"` and status `not_connected`, `saved`, `usable` or
`reconnect_required`. Only first-party human authentication is accepted.

After explicit local destination/account consent, the dedicated CLI helper posts
`{account_id,api_key,expected_connection}` to the same route. First import uses
`expected_connection: null`; replacing a reviewed connection must send its exact
ID and version. Stale consent returns409. The local helper supports only Codex
API-key file storage, never ChatGPT OAuth subscription tokens. It preserves local
files, disables redirects and exposes only redacted results.

`POST /api/v1/providers/codex-connection/verify` accepts
`{"connection":{"id":"<UUID>","state_version":1},"model":"gpt-4.1-mini"}`.
It makes a small paid Responses request through the ordinary metered proxy with
the exact saved service selector. `usable` requires a bounded, completed response
using the current key epoch and service/endpoint binding; another personal or org
credential cannot satisfy verification. Authentication rejection reports
`reconnect_required`; network, body or completion failures do not report ready.

Import, replacement and endpoint/key/service provisioning are transactional.
Same-value user replacement advances credential epoch; verification and lazy
refresh do not. Disable/Delete invalidate live usable status. Explicit reconnect
creates a fresh service when the previous one is disabled or deleted, preserving
its tombstone. NyxID deletion does not revoke an upstream API key or modify local
Codex. See [the lifecycle and consent guide](CODEX_CONNECTION.md) for storage
fallbacks, separate OAuth authorization and release capability checks.

Users connect to providers by submitting API keys or completing OAuth flows. These endpoints manage the user's provider token lifecycle.

#### GET /api/v1/providers/my-tokens

List all provider tokens for the authenticated user.

**Auth:** Required

**Response (200):**

```json
{
  "tokens": [
    {
      "provider_id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "provider_name": "OpenAI",
      "provider_slug": "openai",
      "provider_type": "api_key",
      "status": "active",
      "label": "Production Key",
      "expires_at": null,
      "last_used_at": "2025-06-01T14:22:00+00:00",
      "connected_at": "2025-06-01T10:00:00+00:00"
    }
  ]
}
```

**Token Status Values:**

| Status           | Description                                              |
|------------------|----------------------------------------------------------|
| `active`         | Token is valid and ready for use                         |
| `expired`        | OAuth token has expired (will attempt lazy refresh)      |
| `revoked`        | User disconnected or admin deactivated the provider      |
| `refresh_failed` | OAuth token refresh failed (user must reconnect)         |

**Example:**

```bash
curl http://localhost:3001/api/v1/providers/my-tokens \
  -H "Authorization: Bearer <access_token>"
```

---

#### POST /api/v1/providers/{provider_id}/connect/api-key

Connect to an API key provider by submitting the key. The key is encrypted with AES-256-GCM before storage.

**Auth:** Required

**Path Parameters:**

| Parameter     | Type | Description     |
|---------------|------|-----------------|
| `provider_id` | UUID | The provider ID |

**Request Body:**

| Field     | Type   | Required | Description                            |
|-----------|--------|----------|----------------------------------------|
| `api_key` | string | Yes      | The API key (1-4096 characters)        |
| `label`   | string | No       | Human-readable label for the key       |

```json
{
  "api_key": "sk-proj-abc123...",
  "label": "Production Key"
}
```

**Response (200):**

```json
{
  "status": "connected",
  "message": "API key stored successfully"
}
```

**Errors:**
- `1003 not_found` -- Provider does not exist or is inactive
- `1008 validation_error` -- API key is empty or exceeds 4096 characters

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/providers/p1a2b3c4-d5e6-7890-abcd-ef1234567890/connect/api-key \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "sk-proj-abc123", "label": "My OpenAI Key"}'
```

---

#### GET /api/v1/providers/{provider_id}/connect/oauth

Initiate an OAuth2 connection flow with a provider. Returns the authorization URL that the user should be redirected to. Uses PKCE (S256) when the provider supports it.

**Auth:** Required

**Path Parameters:**

| Parameter     | Type | Description     |
|---------------|------|-----------------|
| `provider_id` | UUID | The provider ID |

**Response (200):**

```json
{
  "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&code_challenge=...&state=..."
}
```

The frontend should redirect the user to this URL. After the user authorizes, the provider redirects back to NyxID's callback endpoint.

**Errors:**
- `1003 not_found` -- Provider does not exist, is inactive, or is not an OAuth2 provider

**Example:**

```bash
curl http://localhost:3001/api/v1/providers/p1a2b3c4-d5e6-7890-abcd-ef1234567890/connect/oauth \
  -H "Authorization: Bearer <access_token>"
```

---

#### GET /api/v1/providers/callback

Generic OAuth callback endpoint. Handles the redirect from OAuth providers after user authorization. Resolves the provider from the `state` parameter, verifies the session user matches, exchanges the code for tokens, and redirects to the frontend callback page.

**Auth:** Required (session cookie)

**Query Parameters:**

| Parameter           | Type   | Required | Description                                |
|---------------------|--------|----------|--------------------------------------------|
| `code`              | string | Yes      | Authorization code from the provider       |
| `state`             | string | Yes      | State parameter (maps to NyxID OAuth state)|
| `error`             | string | No       | Error code from the provider               |
| `error_description` | string | No       | Error description from the provider        |

**Response:** HTTP 302 redirect to `{FRONTEND_URL}/providers/callback?status=success` on success, or `?status=error&message=...` on failure.

This endpoint is not called directly by the frontend. It is the OAuth redirect URI registered with external providers.

---

#### POST /api/v1/providers/callback

OAuth callback endpoint for providers that use `response_mode=form_post` (e.g., Apple). Accepts the authorization code and state as a form body instead of query parameters, then redirects the same way as the GET callback.

**Auth:** Required (session cookie)

**Form Body:**

| Field               | Type   | Required | Description                                |
|---------------------|--------|----------|--------------------------------------------|
| `code`              | string | Yes      | Authorization code from the provider       |
| `state`             | string | Yes      | State parameter (maps to NyxID OAuth state)|
| `error`             | string | No       | Error code from the provider               |
| `error_description` | string | No       | Error description from the provider        |

**Response:** HTTP 302 redirect to `{FRONTEND_URL}/providers/callback?status=success` on success, or `?status=error&message=...` on failure.

---

#### DELETE /api/v1/providers/{provider_id}/disconnect

Disconnect from a provider. Local credentials are atomically claimed and cleared before NyxID schedules any configured, best-effort upstream OAuth revocation.

**Auth:** Required

**Path Parameters:**

| Parameter     | Type | Description     |
|---------------|------|-----------------|
| `provider_id` | UUID | The provider ID |

**Query Parameters:**

| Parameter        | Type    | Required | Description |
|------------------|---------|----------|-------------|
| `target_org_id`  | UUID    | No       | Disconnect an organization-owned provider token; requires organization admin access |
| `cascade_grant`  | boolean | No       | Confirm deletion of every same-owner NyxID connection sharing a grant-level upstream authorization |
| `grant_scope`    | string  | No       | Set to `token` to remove only this connection without revoking the upstream grant |

`cascade_grant=true` and `grant_scope=token` are mutually exclusive and return HTTP 400 when combined. Grant-level providers require explicit cascade confirmation whenever sibling connections exist; NyxID never performs an implicit cascade.

**Response (200):**

```json
{
  "status": "disconnected",
  "message": "Provider disconnected and credentials removed",
  "upstream_revocation_scheduled": true
}
```

`upstream_revocation_scheduled` is `true` when an eligible upstream request was successfully scheduled after local teardown. It does not assert that the detached upstream request was delivered. `false` means no upstream request was scheduled, such as an unconfigured provider or Facebook token-scope removal.

**Errors:**
- `1003 not_found` -- No token found for this provider
- `11500 grant_cascade_confirmation_required` (HTTP 409) -- Explicit cascade or token-scope selection is required; see the structured response below

**Example:**

```bash
curl -X DELETE http://localhost:3001/api/v1/providers/p1a2b3c4-d5e6-7890-abcd-ef1234567890/disconnect \
  -H "Authorization: Bearer <access_token>"
```

---

#### POST /api/v1/providers/{provider_id}/refresh

Manually trigger a token refresh for an OAuth2 provider. For OAuth tokens, this triggers a lazy refresh if the token is within 5 minutes of expiry or already expired.

**Auth:** Required

**Path Parameters:**

| Parameter     | Type | Description     |
|---------------|------|-----------------|
| `provider_id` | UUID | The provider ID |

**Response (200):**

```json
{
  "status": "refreshed",
  "message": "Token refreshed successfully"
}
```

**Errors:**
- `1003 not_found` -- No active token for this provider

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/providers/p1a2b3c4-d5e6-7890-abcd-ef1234567890/refresh \
  -H "Authorization: Bearer <access_token>"
```

---

### Unified Keys (Streamlined Services)

The unified keys API auto-provisions UserEndpoint + UserApiKey + UserService records from a single request. This is the primary entry point for users connecting external services.

#### POST /api/v1/keys

Create a new key from catalog or custom endpoint. Auto-provisions all 3 records (endpoint, credential, service).

**Auth:** Required

**Request Body:**

| Field          | Type   | Required | Description                                        |
|----------------|--------|----------|----------------------------------------------------|
| `service_slug` | string | No       | Catalog service slug (e.g., `"llm-openai"`)        |
| `credential`   | string | Yes      | API key or bearer token                            |
| `label`        | string | No       | Human-readable label                               |
| `endpoint_url` | string | No       | Custom endpoint URL (required for self-hosted services, optional override for catalog) |
| `auth_method`  | string | No       | Auth method: `"bearer"`, `"header"`, `"query"`, `"basic"` (default from catalog or `"bearer"`) |
| `auth_key_name`| string | No       | Auth header/param name (default from catalog or `"Authorization"`) |

**Response (200):** Combined view of endpoint + key + service.

**Errors:**
- `1003 not_found` -- Catalog service not found for given slug
- `1004 conflict` -- User already has a service with this slug

#### GET /api/v1/keys

List all user's keys (combined endpoint + key + service view) for existing human/API-key/delegated callers. CatalogEditor service accounts receive all platform catalog entries with `resource_type: "catalog_service"` and catalog UUIDs when a platform administrator has saved `catalog:skills:read` on the account and the token/live account scopes include it. No catalog role, additional `user-services:read`, or resource grant is required for this scope-granted mode. Existing role-based editors retain their previous role and additional read scope checks until an explicit admin scope save. General/Curation service accounts with `user-services:read` in both the token and live account scopes and a live key read grant receive `{"keys":[...]}` containing only the grant's currently readable, nonsecret metadata entries. See the detail response below for the SA entry fields. Curation accounts also require their live Curation grant.

**Auth:** Required

#### GET /api/v1/keys/{id}

Get a single key's combined view for existing human/API-key/delegated callers. Service accounts receive a smaller nonsecret metadata response. CatalogEditor must use a catalog UUID returned by its `/keys` list; General/Curation must use an exact UserService UUID.

**CatalogEditor auth:** platform-admin scope grant plus token/live `catalog:skills:read`. Existing role-based editors additionally require token/live `user-services:read` and global role permission `nyxid:catalog:skills:read` until an admin saves catalog scopes. The response contains `resource_type: "catalog_service"`. See [Platform catalog editors](SERVICE_ACCOUNTS.md#platform-catalog-editors) for scope setup and compatibility.

**General/Curation SA auth:** `user-services:read` in both the token and live account scopes, an unexpired exact key read grant, and current SA-owner access. Curation accounts also require their live Curation grant. Slug access, HEAD, upgrades, and key writes are not included.

The SA response includes identity/label, service type and active state, catalog association, effective `recommended_skills`/`recommended_skill_refs`, `skills_revision`, and `skills_manifest_digest`. It excludes credentials, raw URLs, headers, frame injections, and routing/authentication configuration. No credential resolution or OAuth reconciliation occurs.

Platform admins manage exact grants with `PUT`/`DELETE /api/v1/admin/service-accounts/{sa_id}/key-read-grant`; admins/operators can inspect them with `GET`. PUT accepts `{"user_service_ids":["<uuid>"],"expires_at":"<optional future RFC3339>"}` and replaces all targets. See [Connection metadata reads](SERVICE_ACCOUNTS.md#connection-metadata-reads) for setup and lifecycle.

**Auth:** Required

#### DELETE /api/v1/keys/{id}

Revoke a key (deactivates the service and credential), then schedule configured best-effort upstream OAuth revocation after local teardown.

**Auth:** Required

**Query Parameters:**

| Parameter          | Type    | Required | Description |
|--------------------|---------|----------|-------------|
| `only_if_pending`  | boolean | No       | Delete only a `pending_auth` placeholder; always local-only and never enters grant cascade handling |
| `cascade_grant`    | boolean | No       | Confirm deletion of every same-owner NyxID connection sharing a grant-level upstream authorization |
| `grant_scope`      | string  | No       | Set to `token` to remove only this service without revoking the upstream grant |

`cascade_grant=true` and `grant_scope=token` are mutually exclusive and return HTTP 400 when combined.

**Response (200):**

```json
{
  "message": "Key revoked successfully",
  "deleted": true,
  "upstream_revocation_scheduled": true
}
```

For `only_if_pending=true`, `deleted` is `false` if authorization already completed and `upstream_revocation_scheduled` is always `false`.

---

### User Endpoints

User-managed target URLs for external services.

#### GET /api/v1/endpoints

List user's endpoints.

**Auth:** Required

#### PUT /api/v1/endpoints/{id}

Update an endpoint's URL or label.

**Auth:** Required

#### DELETE /api/v1/endpoints/{id}

Delete an endpoint.

**Auth:** Required

---

### External API Keys

User's external credentials (distinct from NyxID API keys).

#### GET /api/v1/api-keys/external

List user's external API keys / credentials.

**Auth:** Required

#### PUT /api/v1/api-keys/external/{id}

Update label or rotate credential.

**Auth:** Required

#### DELETE /api/v1/api-keys/external/{id}

Revoke an external credential. OAuth-backed rows use the same grant-cascade and upstream-revocation contract as unified keys.

**Auth:** Required

**Query Parameters:**

| Parameter        | Type    | Required | Description |
|------------------|---------|----------|-------------|
| `cascade_grant`  | boolean | No       | Confirm deletion of every same-owner NyxID connection sharing a grant-level upstream authorization |
| `grant_scope`    | string  | No       | Set to `token` to delete only this credential without revoking the upstream grant |

`cascade_grant=true` and `grant_scope=token` are mutually exclusive and return HTTP 400 when combined.

**Response (200):**

```json
{
  "deleted": true,
  "upstream_revocation_scheduled": true
}
```

This endpoint previously returned HTTP 204. It now returns the JSON response above so clients can distinguish local deletion from an eligible upstream handoff.

#### OAuth grant cascade conflict

The three delete endpoints above return HTTP 409 with error code `11500` when grant revocation would also affect sibling NyxID connections and `cascade_grant=true` was not provided. Nothing is deleted on this response.

```json
{
  "error": "grant_cascade_confirmation_required",
  "error_code": 11500,
  "message": "Grant cascade confirmation required",
  "details": {
    "provider_slug": "github",
    "provider_name": "GitHub",
    "revokes_grant": true,
    "siblings": [
      {
        "user_service_id": "service-id",
        "name": "github-issues",
        "slug": "github-issues"
      }
    ],
    "unaffected_other_app": [],
    "token_scope_available": true
  }
}
```

Clients may retry with `cascade_grant=true`, or with `grant_scope=token` when `token_scope_available` is `true`. A successful response's `upstream_revocation_scheduled` field means an eligible detached request was scheduled, not that the upstream provider confirmed delivery.

---

### User Services

User's proxy routing configuration (binds endpoint + key + auth config + optional node).

#### GET /api/v1/user-services

List user's service bindings.

**Auth:** Required

**Response (200):**

```json
{
  "services": [
    {
      "id": "6fd22b58-0261-4b86-8ce7-73a255a0619d",
      "slug": "github",
      "label": "Work GitHub",
      "catalog_service_name": "GitHub",
      "resource_uri": "https://api.nyxid.dev/api/v1/proxy/s/github",
      "endpoint_id": "985fba62-f4fb-4c71-ae19-e669ae86ca19",
      "api_key_id": "b306c83f-a1f8-4117-a28e-ac1ab84385c0",
      "auth_method": "bearer",
      "auth_key_name": "Authorization",
      "catalog_service_id": "33ab1178-c9d5-40ec-86a2-fc542a97120e",
      "node_priority": 0,
      "ssh_auth_mode": "proxy_only",
      "ssh_node_keys_stale": false,
      "admin_only": false,
      "is_active": true,
      "identity_propagation_mode": "none",
      "identity_include_user_id": false,
      "identity_include_email": false,
      "identity_include_name": false,
      "forward_access_token": false,
      "inject_delegation_token": false,
      "delegation_token_scope": "",
      "ws_frame_injections": [],
      "created_at": "2026-08-05T10:00:00+00:00",
      "updated_at": "2026-08-05T10:00:00+00:00",
      "credential_source": { "type": "personal" }
    }
  ]
}
```

| Field | Type | Notes |
|-------|------|-------|
| `id` | UUID string | Stable UserService identifier |
| `slug` | string | Stable proxy slug; used by `/api/v1/proxy/s/{slug}` |
| `is_active` | boolean | Stable active/inactive contract for the binding |
| `label` | string, omitted | Human-readable endpoint label |
| `catalog_service_name` | string, omitted | Catalog display name |
| `resource_uri` | absolute URI | RFC 8707 resource identifier for this service |
| `endpoint_id` | UUID string | Bound user endpoint |
| `api_key_id` | UUID string, omitted | Bound external credential |
| `auth_method` | string | Credential injection method |
| `auth_key_name` | string | Header or parameter name used for credential injection |
| `catalog_service_id` | UUID string, omitted | Source catalog service |
| `node_id` | UUID string, omitted | Selected credential node |
| `node_priority` | integer | Node routing priority |
| `ssh_auth_mode` | string | `cert`, `node_key`, or `proxy_only` |
| `ssh_node_keys_stale` | boolean | Whether node-key material needs refresh |
| `admin_only` | boolean | Whether the service is restricted to administrators |
| `identity_propagation_mode` | string | `none`, `headers`, `jwt`, or `both` |
| `identity_include_user_id` | boolean | Include user ID in propagated identity |
| `identity_include_email` | boolean | Include email in propagated identity |
| `identity_include_name` | boolean | Include display name in propagated identity |
| `identity_jwt_audience` | string, omitted | Audience for propagated identity JWTs |
| `forward_access_token` | boolean | Forward the caller's access token |
| `inject_delegation_token` | boolean | Inject a delegated NyxID token |
| `delegation_token_scope` | string | Delegated token scope string |
| `custom_user_agent` | string, omitted | Per-service User-Agent override |
| `default_request_headers` | array, omitted | User-owned default request headers |
| `ws_frame_injections` | array | WebSocket frame injection rules |
| `created_at` | RFC 3339 string | Creation timestamp |
| `updated_at` | RFC 3339 string | Last-update timestamp |
| `credential_source` | object | `{ "type": "personal" }` or org provenance with `org_id`, `org_name`, `avatar_url`, `role`, and `allowed` |

The integration contract guarantees `services[].id`, `services[].slug`, and `services[].is_active` across compatible `/api/v1` releases. Other fields are documented for current clients but may evolve additively; clients should ignore unknown fields.

#### PUT /api/v1/user-services/{id}

Update auth config or node routing.

**Auth:** Required

#### DELETE /api/v1/user-services/{id}

Deactivate a service binding.

**Auth:** Required

---

### Third-party Connector Integration

Registered developer apps should use connect links for browser-based connector setup instead of inferring an attempt from changes to `/user-services`.

For channel bot setup, see [Bot connection links](#bot-connection-links). Bot links use the same create-link, human-setup, and signed-notification pattern through separate endpoints.

1. Obtain a normal user OAuth access token through the authorization-code flow.
2. Create a link with `POST /api/v1/connect-links`. When the access token belongs to a registered app, `callback_url` must satisfy that app's registered OAuth redirect URI matching policy. Registered custom schemes and public-client loopback redirects are supported.
3. Open the returned `connect_url` in the user's browser. Credential submission and provider authorization remain human-session-only.
4. On a terminal outcome, the browser returns to the stored callback URI after NyxID adds `status=completed|cancelled|expired` and `connect_link_id=<id>`. Existing query parameters are preserved; reserved status parameters are replaced. Fragments and userinfo are rejected, and the raw connect token is never included.
5. Use `GET /api/v1/connect-links/{id}` as the polling fallback. `POST /api/v1/connect-links/{id}/cancel` cancels an attempt from the creating app.

**Create request:**

```http
POST /api/v1/connect-links
Authorization: Bearer <developer-app-user-access-token>
Content-Type: application/json
```

```json
{
  "service_slug": "github",
  "label": "Work account",
  "scopes": ["public_repo"],
  "callback_url": "desktop-app://connect/return",
  "expires_in": 900
}
```

**Create response:**

```json
{
  "id": "6c02c84a-3d97-430f-8468-c96b609d9563",
  "connect_url": "https://app.nyxid.dev/connect/nyx_clk_<opaque-secret>",
  "expires_at": "2026-08-05T10:15:00.000Z"
}
```

Treat `connect_url` as a single-use secret and hand it only to the browser. The authenticated app ID and display name are recorded on the link; a request-body `requested_by` value cannot override that identity.

`scopes` is an optional array of additional OAuth scopes (default `[]`). Each entry may contain comma- or whitespace-separated scopes; NyxID trims and deduplicates them in order, preserving case. The shared OAuth scope limits apply across the entire request: at most 32 scopes before deduplication, at most 256 characters per scope, and only `[A-Za-z0-9._:/~+*=-]` characters. Scopes supplement the provider defaults for OAuth and RFC 8628 device-code flows; they do not replace defaults, and the provider decides which permissions to grant. Stored scopes survive provider denial and retry.

`endpoint_url` is an optional HTTP(S) service URL prefill for connectors that require a gateway URL. It appears as an editable Service URL on the hosted page; the user confirms the final value during completion. It is ignored when the user selects a NyxID platform key.
The CLI accepts the same value through `nyxid connect <service_slug> --endpoint-url <url>`.

Creation returns HTTP 400 (`AppError::ValidationError`) for malformed/oversized scopes or non-empty scopes on API-key/no-auth services, providers with `supports_oauth_scopes = false`, and OpenAI-format device-code providers. An empty list preserves the existing behavior for every connection method.

**Public preview:** `POST /api/v1/connect-links/preview` with `{ "token": "nyx_clk_<opaque-secret>" }` returns service and request details, including `connect_method` (`oauth`, `device_code`, `api_key`, or `none`) and `scopes: ["public_repo"]`. The `scopes` array is always present, possibly empty, including for legacy stored links. The hosted page displays these creator-selected permissions for human review; completion cannot edit them.

**Polling response:**

```json
{
  "id": "6c02c84a-3d97-430f-8468-c96b609d9563",
  "status": "pending",
  "service_name": "GitHub",
  "service_slug": "github",
  "expires_at": "2026-08-05T10:15:00.000Z",
  "scopes": ["public_repo"],
  "requesting_app_id": "desktop-client-id",
  "requesting_app_name": "Desktop App",
  "last_error": "provider_access_denied",
  "last_error_at": "2026-08-05T10:04:12.000Z"
}
```

`status` is one of `pending`, `completed`, `expired`, or `cancelled`. A completed response includes `connected_service: { "id", "slug" }`. Terminal responses with a callback include the fully merged `callback_url`.

Polling always includes `scopes` (possibly `[]`) in every state. MCP `nyx__connect_service` accepts the same optional `scopes` array, or a comma/space-separated string, and echoes normalized scopes in its `pending_connection` response. Omit `credential` to use the hosted OAuth flow when requesting scopes.

`last_error` is an optional short, stable, metadata-only code. `provider_access_denied` means the provider consent screen was declined, but the link remains `pending` and may be retried within its TTL and finalization grace. The field is cleared when a later attempt succeeds. Its absence means no provider decline has been recorded; it does not prove that the browser is still open.

#### Connection lifecycle webhooks

A developer app can register one HTTPS webhook for server-side lifecycle delivery. The target must resolve only to public IP addresses. Configure and rotate endpoints return the signing secret exactly once; normal app reads never include it.

```http
PUT /api/v1/developer/oauth-clients/{client_id}/connection-webhook
Authorization: Bearer <human-session-access-token>
Content-Type: application/json

{"url":"https://desktop.example.com/nyxid/events"}
```

```json
{
  "client_id": "desktop-client-id",
  "connection_webhook_url": "https://desktop.example.com/nyxid/events",
  "connection_webhook_enabled": true,
  "signing_secret": "nyx_cwh_<opaque-secret>",
  "key_id": "key_0123456789abcdef"
}
```

- `POST /api/v1/developer/oauth-clients/{client_id}/connection-webhook/rotate-secret` rotates and returns a new secret plus its non-secret `key_id`.
- `DELETE /api/v1/developer/oauth-clients/{client_id}/connection-webhook` disables delivery and removes the stored encrypted secret.

Events are `connect_link.completed`, `connect_link.cancelled`, `connect_link.expired`, and `connection.expired`. Only links created by the app produce connect-link events. Connection expiry routes through the `source_app_id` recorded when that link provisions its service.

Apps that also create [bot connection links](#bot-connection-links) receive `channel_connect.completed`, `channel_connect.cancelled`, and `channel_connect.expired` through this registered webhook and signing key. Existing service event names and payloads are unchanged.

Abandoned app-bound links are expired by a background sweep, so `connect_link.expired` delivery does not require the app to poll or revisit the hosted page.

```json
{
  "event_id": "3cc24472-c0b4-436c-a42a-17f43087f3e7",
  "event_type": "connect_link.completed",
  "occurred_at": "2026-08-06T09:30:00.123Z",
  "data": {
    "user_id": "user-uuid",
    "connect_link_id": "6c02c84a-3d97-430f-8468-c96b609d9563",
    "service_id": "catalog-service-id",
    "service_slug": "service-slug",
    "status": "completed",
    "user_service_id": "user-service-id",
    "completed_at": "2026-08-06T09:29:59.000Z",
    "expires_at": "2026-08-06T09:45:00.000Z"
  }
}
```

Every event's `data.user_id` is the NyxID subject whose connection changed. `connection.expired` also includes `connect_link_id` when the service was provisioned through a connect link; legacy and manually provisioned services omit that field.

The following request headers are a stable contract for connection and outbound trigger webhooks:

- `X-NyxID-Event`: event type, such as `connect_link.completed` or `trigger.event`.
- `X-NyxID-Delivery-Id`: the envelope event ID. Retries and connect-link outbox redispatches retain the same value.
- `X-NyxID-Key-Id`: non-secret signing-key identifier returned with the one-time secret.
- `X-NyxID-Timestamp`: Unix seconds included in the signed content.
- `X-NyxID-Signature`: `sha256=<hex>` HMAC-SHA256 signature.

Verify HMAC-SHA256 over the exact bytes `timestamp + "." + raw_request_body`, reject stale timestamps, select the held secret using `X-NyxID-Key-Id`, and compare in constant time:

```python
import hashlib
import hmac

signing_secret = secrets_by_key_id[key_id]
signed = timestamp.encode() + b"." + raw_body
expected = hmac.new(signing_secret.encode(), signed, hashlib.sha256).hexdigest()
valid = hmac.compare_digest(signature.removeprefix("sha256="), expected)
```

For zero-gap rotation, keep the current and previous secrets in a receiver map keyed by `key_id`, call the rotate endpoint, accept either key, and remove the old slot only after observing deliveries with the new `X-NyxID-Key-Id`.

Connect-link terminal events use the link document as a durable outbox. Each dispatch cycle makes up to three attempts with short timeouts and bounded backoff. A stale undelivered reservation is reclaimed by the expiry sweep after 120 seconds, for at most five dispatch cycles. Delivery is at least once: a process crash after the receiver accepts but before NyxID records success can produce a duplicate with the same event ID. After the cap, the outbox is marked `abandoned` and a metadata-only final-failure audit is emitted.

`connection.expired` is best effort because it has no durable outbox: it receives one bounded three-attempt cycle and is not redelivered after process loss or final failure. Integrations should periodically reconcile with authenticated `GET /api/v1/user-services`; its cheap `connection_status` field is `active` or `expired` when credential expiry is knowable.

Connection webhook bodies are metadata-only and enforced at a maximum of 16 KiB. Delivery never rolls back a link or credential transition, and event bodies and secrets are never logged.

Envelope timestamps use RFC 3339 UTC serialization. The wire-format assertion emits the example above byte-for-byte, including `2026-08-06T09:30:00.123Z`.

---

### Bot connection links

Tracked bot setup uses `POST /api/v1/channel-connect-links` and the hosted page `/connect/bot/{token}`. Existing [service connection links](#third-party-connector-integration) retain their API and webhook contracts. Reusable `/channel-bots/connect/{platform}` pages remain available; those URLs do not create a tracked callback request.

#### POST /api/v1/channel-connect-links

**Auth:** Account session, user OAuth access token, or Agent Key with write access to the selected owner. Delegated, relay, and service-account tokens are rejected. Agent Keys may create, read, and cancel requests; setup completion requires a human account.

**Create request for a direct webhook:**

```json
{
	"platform": "discord",
	"label": "Support bot",
	"requested_by": "Support platform",
	"webhook_url": "https://app.example.com/events/nyxid",
	"callback_url": "https://app.example.com/setup/return?state=request-123",
	"expires_in": 900
}
```

| Field | Required | Contract |
|---|---|---|
| `platform` | Yes | Enabled platform ID from `GET /api/v1/channel-platforms`. |
| `label` | Yes | Fixed bot name. |
| `target_org_id` | No | Organization UUID the actor administers. Omit for personal ownership. |
| `requested_by` | No | Display name. Verified OAuth app or Agent Key attribution takes precedence. |
| `webhook_url` | No | Public HTTPS destination for direct callers. OAuth app callers use their registered connection webhook and cannot supply this field. |
| `callback_url` | No | Browser return URI. OAuth app callbacks use the existing registered redirect matching policy; other callers use HTTP(S) URLs. |
| `expires_in` | No | Seconds, default `900`, clamped to `60`–`3600`. |

**Response: `200 OK`**

```json
{
	"id": "6c02c84a-3d97-430f-8468-c96b609d9563",
	"connect_url": "https://app.nyxid.dev/connect/bot/nyx_bcl_<opaque-secret>",
	"expires_at": "2026-09-30T08:15:00Z",
	"webhook_signing_secret": "nyx_bwh_<opaque-secret>",
	"webhook_signing_key_id": "key_<opaque-id>"
}
```

The signing fields are returned once for a direct webhook and are `null` otherwise. The hosted token is a single-use secret. Status, preview, browser callbacks, and notification events never return credentials or signing secrets. The platform, label, and owner are fixed at creation.

#### Status, cancellation, and hosted setup endpoints

All paths below are under `/api/v1/channel-connect-links`.

| Method | Path | Access and behavior |
|---|---|---|
| `GET` | `/{id}` | Authorized owner writer; returns status and webhook delivery state, and reconciles saved setup. |
| `POST` | `/{id}/cancel` | Authorized owner writer; cancels an unstarted request. Started setup returns a conflict. |
| `POST` | `/preview` | Public, rate-limited; accepts `{ "token": "..." }`. Omits owner, bot, provider, callback, and delivery details. |
| `POST` | `/decline` | Human account with owner write access; accepts `{ "token": "..." }` and uses the same cancellation rules. |
| `POST` | `/complete` | Human account; accepts the token and the platform's manual registration fields. |
| `POST` | `/managed/start` | Human account; accepts the token and starts the platform's managed OAuth authorization. |
| `POST` | `/managed/complete` | Human account; accepts the token and managed completion fields. Supports JSON and `Accept: text/event-stream` progress. |
| `POST` | `/telegram/start` | Human account; accepts the token and creates or resumes the linked Telegram approval request. |
| `POST` | `/retry` | Human account; accepts the token and repairs or verifies an already saved bot. |

`status` is `pending`, `completed`, `cancelled`, or `expired`. The private status response includes `bot_id`, `connection_id`, `telegram_request_id`, `last_error`, and `delivery_status`. Delivery is `pending`, `delivered`, `abandoned`, or `none` after a terminal result; before that it may be `null`. `telegram_requires_original_actor` tells another org administrator that the account which started Telegram approval must resume it. A terminal `callback_url` includes the merged `status`, `channel_connect_link_id`, and optional `bot_id` parameters.

#### Bot setup notifications

Events are `channel_connect.completed`, `channel_connect.cancelled`, and `channel_connect.expired`. They use the [connection lifecycle signature headers and HMAC contract](#connection-lifecycle-webhooks). The event ID, occurrence time, and result data remain stable across retries. Receivers deduplicate by `event_id` and acknowledge with a 2xx response.

Bot delivery uses five-minute leases and at most five cycles of three bounded HTTP attempts. A separate worker recovers completion, expiry, and interrupted delivery without app polling. `CONNECT_LINK_EXPIRY_SWEEP_INTERVAL_SECS=0` disables both the bot worker and the existing service-link expiry sweep.

For manual setup, `completed` can include `bot_status: "pending_webhook"`. `bot_status` and `webhook_registered` describe whether platform delivery is ready. The optional browser return follows explicit user continuation so the user can save a one-time platform verification secret first.

The [bot-link lifecycle and webhook payload](CHANNEL_BOT_RELAY.md#tracked-bot-connection-links) describe recovery deadlines, Telegram approval expiry, and late worker completion. The [implementation map](CHANNEL_BOT_RELAY.md#bot-link-implementation-and-compatibility) identifies the storage, handler, worker, frontend, and CLI code.

---

### Service Catalog

Read-only catalog of available service templates for users.

#### GET /api/v1/catalog

List all available service templates from the admin-managed catalog.

**Auth:** Session cookie, human access token, general `nyx_` or scoped/platform `nyxid_ag_` API key (via `X-API-Key` or `Authorization: Bearer`; no proxy scope required). Scheduled-invocation keys, service accounts, and relay tokens are rejected. Delegated tokens retain the existing exact `account:read` GET exception.

#### GET /api/v1/catalog/{slug}

Get a specific catalog template by slug.

**Auth:** Session cookie, human access token, general `nyx_` or scoped/platform `nyxid_ag_` API key (via `X-API-Key` or `Authorization: Bearer`; no proxy scope required). Scheduled-invocation keys, service accounts, and relay tokens are rejected. Delegated tokens retain the existing exact `account:read` GET exception.

#### GET /api/v1/catalog/{slug}/endpoints

Return operations parsed from the admin-configured catalog OpenAPI spec. If no readable catalog template matches, a readable user-service slug can resolve its owner-scoped mounted spec.

**Auth:** Session cookie, human access token, general `nyx_` or scoped/platform `nyxid_ag_` API key (via `X-API-Key` or `Authorization: Bearer`; no proxy scope required). Scheduled-invocation keys, service accounts, and relay tokens are rejected. Delegated tokens retain the existing exact `account:read` GET exception.

Service accounts remain rejected: catalog detail resolves restricted platform grants through a User actor, while SA tokens carry the SA ID.

Catalog entries use template slugs, resource URIs and skills, with live platform grants determining `platform_key.available` and inference binding/status. They do not include instance overrides or connection flags. API keys can use instance-backed private catalog access and mounted-spec fallback only within their effective service allowlist, including auto-connected expansion, and active Member/Admin org scopes. Org-owned keys act as the org. Catalog discovery does not provision services or reconcile pending OAuth credentials.

---

### Sessions

#### GET /api/v1/sessions

List all active (non-revoked, non-expired) sessions for the authenticated user. Sessions are returned in reverse chronological order.

**Auth:** Required

**Response (200):**

```json
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
    "created_at": "2025-06-01T14:22:00+00:00",
    "expires_at": "2025-07-01T14:22:00+00:00"
  }
]
```

**Example:**

```bash
curl http://localhost:3001/api/v1/sessions \
  -H "Authorization: Bearer <access_token>"
```

---

### Service Pools

Service pools group owned connections under one proxy slug. Management and
inspection require authentication and owner access. Organization management
requires an owner or admin membership. The full routing, member, and retry
contracts are documented in [Service pools](SERVICE_POOLS.md).

| Method | Path under `/api/v1` | Purpose |
|---|---|---|
| GET / POST | `/service-pools` | List or create pools; optional `org_id` selects an organization owner |
| GET / PUT / DELETE | `/service-pools/{pool_id}` | Read, update, or delete a pool |
| PUT / POST | `/service-pools/{pool_id}/members` | Replace all members or add a member |
| DELETE | `/service-pools/{pool_id}/members/{user_service_id}` | Remove a member |
| GET | `/service-pools/candidates` | Inspect connections for a new pool |
| GET | `/service-pools/{pool_id}/candidates` | Inspect connections for an existing pool or draft |
| GET | `/service-pools/{pool_id}/health` | Inspect all saved members, including unavailable members |
| POST | `/service-pools/{pool_id}/health/reset` | Reset cooldowns for one member or the whole pool |

Updates accept `expected_revision`; a stale revision returns HTTP 409. Settings
and members can be saved in the same update. Health reset accepts
`{"user_service_id":"<connection-id>"}` for one member or `{}` for all members.

Candidate and health inspection accept these query parameters:

| Parameter | Behavior |
|---|---|
| `check_operation` | Defaults to `true`. Set `false` to browse connection inventory without checking operation permissions or cooldowns. |
| `method`, `path` | Checked operation, defaulting to `POST /` for Same API or `POST chat/completions` for AI chat. Paths follow proxy canonical-path validation. |
| `strategy`, `member_contract` | Draft routing strategy and contract for candidate inspection. Health uses the saved configuration. |
| `peer_ids`, `declared_peer_ids` | Comma-separated draft connection UUIDs and Same API compatibility declarations, capped at 50 IDs each. |
| `selected_only` | With `true`, candidate inspection returns the selected `peer_ids` independently of search and pagination. |
| `search`, `limit`, `after` | Case-insensitive name or slug search, applied before candidate pagination. `limit` defaults to 100 and is clamped to 1–100. |
| `org_id` | Organization owner for new-pool candidate inspection. Existing-pool routes resolve the owner from the pool. |

Responses contain `operation_checked`, `method`, `path`, `candidates`,
`has_more`, and `next_cursor`. Explicit inventory mode returns
`operation_checked: false` and null method/path values. Each candidate includes
its connection ID, `name`, `slug`, eligibility and reason, credential binding,
protocol, compatibility requirements, and cooldown metadata. Inventory results
do not establish that a particular operation can execute. Inspection is
read-only and never decrypts credentials or sends a request to a provider.

A connection with an inactive stored credential or missing credential material
returns `eligible: false` with `reason: "credential_unavailable"`; other
connections remain in the response. Repair that connection before selecting it.
Priority execution skips such members before dispatch. Database and data
integrity errors still fail the request.

### Proxy

#### ANY /api/v1/proxy/{service_id}/{*path}

Forward any HTTP request to a registered downstream service. NyxID resolves the service, verifies the user has an active connection, decrypts the appropriate credential, and injects it into the outbound request using the configured auth method.

**Connection enforcement:** An active `UserServiceConnection` is always required before proxying. For `connection` category services, the per-user encrypted credential is used. For `internal` category services, the service-level master credential is used. `provider` services are not proxyable.

**Path validation:** Paths containing `..` or `//` are rejected to prevent path traversal attacks.

**Auth:** Required

**Path Parameters:**

| Parameter    | Type   | Description                                    |
|--------------|--------|------------------------------------------------|
| `service_id` | UUID   | The downstream service ID                      |
| `*path`      | string | The path to forward (appended to service base URL) |

**Supported Methods:** GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS

**Request:** The request body, query parameters, and allowed headers are forwarded to the downstream service. Only safe headers are forwarded (content-type, accept, accept-language, accept-encoding, content-length, user-agent, x-request-id, x-correlation-id).

**Identity Propagation:** If the service has `identity_propagation_mode` set to `headers` or `both`, NyxID injects identity headers (`X-NyxID-User-Id`, `X-NyxID-User-Email`, `X-NyxID-User-Name`) based on the service configuration. If set to `jwt` or `both`, a short-lived RS256-signed identity assertion JWT is added as `X-NyxID-Identity-Token` (60-second lifetime).

**Credential Delegation:** If the service has provider requirements configured, NyxID resolves the user's provider tokens and injects them into the outbound request. Required provider tokens cause the request to fail if missing; optional tokens are silently skipped.

**Delegation Token Injection:** If the service has `inject_delegation_token: true`, NyxID generates a short-lived delegated access token (5-minute TTL) and injects it as the `X-NyxID-Delegation-Token` header. This allows the downstream service to call NyxID APIs on behalf of the user according to the admin-configured service scope. Proxy and LLM scopes retain their existing behavior; the service-only `account:read` scope adds GET-only management parity with explicit route-class and WebSocket exclusions. Other eligible scopes can be refreshed via `POST /api/v1/delegation/refresh` for long-running workflows, but refresh cannot re-add `account:read`; the service must receive a newly minted token from an eligible invocation. See [Token Exchange (Delegated Access)](#token-exchange-delegated-access) for details.

**Assistant Forward Token (transitional, assistant mount only):** Not a new identity mode. On the `/api/v1/assistant/*` pass-through, a browser session authenticates with a cookie and therefore carries no bearer for `forward_access_token` to forward. While the `aevatar` service row has `forward_access_token: true`, NyxID mints a **delegated access token** for the session user (the same `delegated: true` capability token described under Delegation Token Injection, scoped `proxy`, 5-minute TTL, `act.sub = "aevatar"`) and sends it as `Authorization: Bearer` alongside the standard identity headers above (which flow unchanged). Aevatar reuses that bearer to call NyxID's LLM/proxy routes on the user's behalf; because it is a delegated token, `reject_delegated_tokens` keeps a leaked copy off every account-management, admin, and key surface while the proxy/LLM routes accept it. It is delivered in `Authorization` rather than `X-NyxID-Delegation-Token` only because Aevatar's currently deployed validator reads `Authorization`. Unlike identity/delegation *injection* (which log and continue on generation failure), a mint failure fails the assistant request: the token is required authentication for the downstream today. Flipping the row to `forward_access_token: false` (the identity-token rollout, with `inject_delegation_token: true`) retires this Authorization mint and hands over to the standard `X-NyxID-Delegation-Token` header with no code change.

**Response:** The downstream service's response status code, allowed headers, and body are returned directly. Only a safe allowlist of response headers is forwarded.

**Streaming:** If the client sends `Accept: text/event-stream` or the upstream responds with `Content-Type: text/event-stream`, NyxID forwards the SSE stream without buffering and strips `content-length`.

**Transaction Approval:** If the resource owner has `approval_required` enabled, has at least one active notification channel, and the request uses a non-session auth method (API key, delegated token, service account, or access token), the proxy checks for an existing approval grant. If no grant exists, an approval request is created (with Telegram notification if configured) and the **HTTP connection is held open** until the user approves/rejects or the configured timeout expires. If approved, the request proceeds and the downstream response is returned. If rejected or timed out, a `403 Forbidden` is returned. The implicit global default is suspended while the owner has no active notification channel and never applies to auto-connected (auto-provisioned, credential-free) services. Explicit per-service `ServiceApprovalConfig` rows apply regardless of channel availability or the auto-connected exemption. Direct browser sessions (session cookie auth) bypass approval.

**Limits:** Request body is limited to 10 MB for proxy requests.

**Errors:**
- `1000 bad_request` -- Service is inactive, service is a provider, invalid proxy path, or connection missing credential
- `1002 forbidden` -- No active connection to this service, or approval was rejected/timed out
- `1003 not_found` -- Service does not exist

**Example:**

```bash
# GET request through proxy
curl http://localhost:3001/api/v1/proxy/d1e2f3a4-b5c6-7890-1234-567890abcdef/v1/reports \
  -H "Authorization: Bearer <access_token>"

# POST request through proxy
curl -X POST http://localhost:3001/api/v1/proxy/d1e2f3a4-b5c6-7890-1234-567890abcdef/v1/events \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"event": "page_view", "page": "/home"}'
```

---

#### ANY /api/v1/proxy/s/{slug}/{*path}

Forward any HTTP request to a downstream service using the service's slug instead of its UUID. This endpoint is functionally identical to `ANY /api/v1/proxy/{service_id}/{*path}` but provides developer-friendly URLs.

The slug is resolved to the service UUID internally. All proxy behavior (credential injection, identity propagation, delegation token injection, transaction approval, path validation, header allowlists, body size limits) is the same as the UUID-based endpoint.

Only active services are resolved by slug. Inactive services return `1003 not_found`.

**Auth:** Required

**Path Parameters:**

| Parameter | Type   | Description                                        |
|-----------|--------|----------------------------------------------------|
| `slug`    | string | The service slug (e.g., `stripe`, `analytics`)     |
| `*path`   | string | The path to forward (appended to service base URL) |

**Supported Methods:** GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS

**Errors:**
- `1000 bad_request` -- Service is inactive, service is a provider, invalid proxy path, or connection missing credential
- `1002 forbidden` -- No active connection to this service
- `1003 not_found` -- No active service with this slug

**Example:**

```bash
# GET request via slug with API key
curl http://localhost:3001/api/v1/proxy/s/stripe/v1/charges \
  -H "X-API-Key: nyx_k_a1b2c3d4..."

# POST request via slug with Bearer token
curl -X POST http://localhost:3001/api/v1/proxy/s/analytics/v1/events \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"event": "page_view", "page": "/home"}'
```

---

### Proxy Service Discovery

#### GET /api/v1/proxy/services

List downstream services available for proxying, with their connection status and proxy URLs. This endpoint is designed for developers integrating via API keys who need to discover available services and construct proxy URLs.

Services with `service_category = "provider"` are excluded (not proxyable). Only active services are returned.

**Auth:** Required

**Query Parameters:**

| Parameter  | Type   | Default | Description                                |
|------------|--------|---------|--------------------------------------------|
| `page`     | int    | 1       | Page number (minimum 1)                    |
| `per_page` | int    | 50      | Results per page (maximum 100)             |

**Response (200):**

```json
{
  "services": [
    {
      "id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
      "name": "Stripe API",
      "slug": "stripe",
      "description": "Payment processing",
      "service_category": "connection",
      "connected": true,
      "requires_connection": true,
      "has_node_binding": false,
      "proxy_url": "http://localhost:3001/api/v1/proxy/d1e2f3a4-b5c6-7890-1234-567890abcdef/{path}",
      "proxy_url_slug": "http://localhost:3001/api/v1/proxy/s/stripe/{path}",
      "docs_url": "http://localhost:3001/api/v1/proxy/services/d1e2f3a4-b5c6-7890-1234-567890abcdef/docs",
      "openapi_url": "http://localhost:3001/api/v1/proxy/services/d1e2f3a4-b5c6-7890-1234-567890abcdef/openapi.json",
      "asyncapi_url": null,
      "streaming_supported": true
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Internal Analytics",
      "slug": "analytics",
      "description": "Internal analytics service",
      "service_category": "internal",
      "connected": false,
      "requires_connection": false,
      "has_node_binding": true,
      "proxy_url": "http://localhost:3001/api/v1/proxy/a1b2c3d4-e5f6-7890-abcd-ef1234567890/{path}",
      "proxy_url_slug": "http://localhost:3001/api/v1/proxy/s/analytics/{path}",
      "docs_url": null,
      "openapi_url": null,
      "asyncapi_url": null,
      "streaming_supported": false
    }
  ],
  "total": 2,
  "page": 1,
  "per_page": 50
}
```

**Response Fields:**

| Field                          | Type    | Description                                               |
|--------------------------------|---------|-----------------------------------------------------------|
| `services[].id`               | string  | Service UUID                                              |
| `services[].name`             | string  | Service display name                                      |
| `services[].slug`             | string  | Service slug (used in slug-based proxy URL)               |
| `services[].description`      | string? | Service description (nullable)                            |
| `services[].service_category` | string  | `"connection"` or `"internal"`                            |
| `services[].connected`        | bool    | Whether the authenticated user has an active connection   |
| `services[].requires_connection` | bool | Whether a connection is required before proxying          |
| `services[].has_node_binding` | bool    | Whether the authenticated user currently has a viable node route for the service |
| `services[].proxy_url`        | string  | UUID-based proxy URL template (replace `{path}`)         |
| `services[].proxy_url_slug`   | string  | Slug-based proxy URL template (replace `{path}`)         |
| `services[].docs_url`         | string? | Scalar UI URL for the downstream service                  |
| `services[].openapi_url`      | string? | Proxied downstream OpenAPI document URL                   |
| `services[].asyncapi_url`     | string? | Proxied downstream AsyncAPI document URL                  |
| `services[].streaming_supported` | bool | Whether the service advertises SSE or other streaming support |
| `total`                       | int     | Total number of matching services                         |
| `page`                        | int     | Current page number                                       |
| `per_page`                    | int     | Results per page                                          |

**Errors:**
- `1001 unauthorized` -- Missing or invalid credentials

**Example:**

```bash
# Discover services with API key
curl http://localhost:3001/api/v1/proxy/services \
  -H "X-API-Key: nyx_k_a1b2c3d4..."

# With pagination
curl "http://localhost:3001/api/v1/proxy/services?page=1&per_page=10" \
  -H "Authorization: Bearer <access_token>"
```

---

### LLM Gateway

The LLM Gateway provides unified access to multiple LLM providers through NyxID. Users connect their provider credentials (API keys or OAuth tokens) via the Providers endpoints, and the gateway handles routing, credential injection, and format translation.

Three access modes are available:
1. **Provider-specific proxy** -- Direct passthrough to a specific provider's API
2. **OpenAI-compatible gateway** -- Routes by model name and translates between API formats
3. **Status endpoint** -- Check which providers are ready for the current user

Streaming is supported for providers that expose SSE-compatible streaming APIs. When the request sets `"stream": true`, NyxID returns `text/event-stream` and forwards or translates provider SSE events on the fly.

**Transaction Approval:** The same blocking approval flow applies to LLM gateway endpoints as to the proxy. If the resource owner has `approval_required` enabled, has at least one active notification channel, and the request uses a non-session auth method (API key, delegated token, service account, or access token), the connection is held open until the user approves/rejects or the timeout expires. The implicit global default is suspended while the owner has no active notification channel and never applies to auto-connected (auto-provisioned, credential-free) services. Explicit per-service `ServiceApprovalConfig` rows apply regardless of channel availability or the auto-connected exemption. See the [Proxy](#proxy) section for details.

#### GET /api/v1/llm/status

Return which LLM providers the authenticated user can use, along with their proxy URLs.

**Auth:** Required

**Response (200):**

```json
{
  "providers": [
    {
      "provider_slug": "openai",
      "provider_name": "OpenAI",
      "status": "ready",
      "proxy_url": "http://localhost:3001/api/v1/llm/openai/v1"
    },
    {
      "provider_slug": "anthropic",
      "provider_name": "Anthropic",
      "status": "not_connected",
      "proxy_url": "http://localhost:3001/api/v1/llm/anthropic/v1"
    }
  ],
  "gateway_url": "http://localhost:3001/api/v1/llm/gateway/v1",
  "supported_models": [
    "gpt-*", "o1-*", "o3-*", "o4-*", "chatgpt-*",
    "claude-*", "gemini-*",
    "mistral-*", "codestral-*", "pixtral-*", "ministral-*", "open-mistral-*",
    "command-*", "embed-*", "rerank-*"
  ]
}
```

**Response Fields:**

| Field               | Type   | Description                                           |
|---------------------|--------|-------------------------------------------------------|
| `providers`         | array  | Per-provider status entries                           |
| `providers[].provider_slug` | string | Provider identifier (e.g., `openai`, `anthropic`) |
| `providers[].provider_name` | string | Display name                                    |
| `providers[].status` | string | `ready`, `not_connected`, or `expired`               |
| `providers[].proxy_url` | string | Direct proxy URL for this provider               |
| `gateway_url`       | string | OpenAI-compatible gateway URL                        |
| `supported_models`  | array  | Model name prefixes the gateway can route            |

**Example:**

```bash
curl http://localhost:3001/api/v1/llm/status \
  -H "Authorization: Bearer <access_token>"
```

---

#### ANY /api/v1/llm/{provider_slug}/v1/{*path}

Forward any HTTP request to a specific LLM provider's API. NyxID resolves the auto-seeded downstream service for the provider, injects the user's stored credential, and proxies the request. No request or response translation is applied -- the request is forwarded as-is.

**Auth:** Required

**Path Parameters:**

| Parameter       | Type   | Description                                         |
|-----------------|--------|-----------------------------------------------------|
| `provider_slug` | string | Provider identifier: `openai`, `openai-codex`, `anthropic`, `google-ai`, `mistral`, `cohere` |
| `*path`         | string | API path to forward (e.g., `chat/completions`)      |

**Supported Methods:** GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS

**Request:** The request body, query parameters, and allowed headers are forwarded to the provider's API. The user's stored credential is injected automatically using the provider's configured auth method.

**Response:** The provider's response status code, allowed headers, and body are returned directly.

**Limits:** Request body limited to 10 MB. Response body limited to 50 MB.

**Errors:**
- `1003 not_found` -- Provider slug not found
- `1000 bad_request` -- Provider credentials not available (user has not connected)
- `1000 bad_request` -- Streaming not yet supported
- `1006 internal_error` -- Auto-seeded LLM service not configured for provider

**Example (OpenAI):**

```bash
curl -X POST http://localhost:3001/api/v1/llm/openai/v1/chat/completions \
  -H "Authorization: Bearer <nyxid_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 100
  }'
```

**Example (Anthropic native format):**

```bash
curl -X POST http://localhost:3001/api/v1/llm/anthropic/v1/messages \
  -H "Authorization: Bearer <nyxid_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 100
  }'
```

---

#### ANY /api/v1/llm/gateway/v1/{*path}

OpenAI-compatible gateway. Accepts requests in OpenAI chat completions format, determines the target provider from the `model` field, translates the request/response format if needed, and returns the result in OpenAI format.

**Auth:** Required

**Path Parameters:**

| Parameter | Type   | Description                                           |
|-----------|--------|-------------------------------------------------------|
| `*path`   | string | API path (typically `chat/completions`)               |

**Request Body:**

The request body must be valid JSON with a `model` field. The gateway uses the model name to determine which provider to route to.

| Field       | Type   | Required | Description                                        |
|-------------|--------|----------|----------------------------------------------------|
| `model`     | string | Yes      | Model name (determines routing)                    |
| `messages`  | array  | Yes      | Chat messages in OpenAI format                     |
| `max_tokens`| number | No       | Maximum tokens to generate (defaults to 4096 for Anthropic) |
| `temperature`| number| No       | Sampling temperature                               |
| `stream`    | boolean| No       | When `true`, return an SSE stream if the selected provider supports streaming |

**Model-to-Provider Routing:**

| Model Prefix | Provider | Notes |
|-------------|----------|-------|
| `gpt-*`, `o1-*`, `o3-*`, `o4-*`, `chatgpt-*` | OpenAI | Falls back to OpenAI Codex if OpenAI not connected |
| `claude-*` | Anthropic | Request/response translated automatically |
| `gemini-*` | Google AI | Routed through Google's OpenAI-compatible endpoint |
| `mistral-*`, `codestral-*`, `pixtral-*`, `ministral-*`, `open-mistral-*` | Mistral | Native OpenAI-compatible format |
| `command-*`, `embed-*`, `rerank-*` | Cohere | Native format passthrough |

**Format Translation (Anthropic):**

When routing to Anthropic, the gateway automatically:
- Extracts `system` role messages into Anthropic's top-level `system` field
- Maps `stop` to `stop_sequences`
- Changes path from `chat/completions` to `messages`
- Adds `anthropic-version: 2023-06-01` header
- Translates the response back to OpenAI format (content, usage, finish_reason)

**Response (200):** OpenAI chat completion format regardless of the target provider.

```json
{
  "id": "chatcmpl-msg_01XFDUDYJgAACzvnptvVoYEL",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "claude-sonnet-4-5-20250929",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Hello! How can I help?"},
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 10,
    "total_tokens": 35
  }
}
```

**Error Response (gateway errors):**

When the upstream provider returns an error, the gateway wraps it in OpenAI error format:

```json
{
  "error": {
    "message": "Error message from upstream provider",
    "type": "gateway_error",
    "code": 400
  }
}
```

**Errors:**
- `1008 validation_error` -- Request body missing or `model` field not present
- `1000 bad_request` -- Unknown model (cannot determine provider), provider not connected, or invalid JSON body

**Example (OpenAI model):**

```bash
curl -X POST http://localhost:3001/api/v1/llm/gateway/v1/chat/completions \
  -H "Authorization: Bearer <nyxid_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello"}
    ],
    "max_tokens": 100
  }'
```

**Example (Anthropic model via gateway):**

```bash
curl -X POST http://localhost:3001/api/v1/llm/gateway/v1/chat/completions \
  -H "Authorization: Bearer <nyxid_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello"}
    ],
    "max_tokens": 1024
  }'
```

**Example (Google AI model via gateway):**

```bash
curl -X POST http://localhost:3001/api/v1/llm/gateway/v1/chat/completions \
  -H "Authorization: Bearer <nyxid_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.0-flash",
    "messages": [
      {"role": "user", "content": "Hello"}
    ],
    "max_tokens": 100
  }'
```

---

### OAuth / OpenID Connect

NyxID implements the OpenID Connect Authorization Code flow with mandatory PKCE.

#### GET /oauth/authorize

Authorization endpoint. Validates the OAuth client and parameters, then issues an authorization code. Only `response_type=code` is supported. PKCE with `S256` method is required for all requests.

**Auth:** Required (the user must be logged in)

**Query Parameters:**

| Parameter               | Type   | Required | Description                              |
|-------------------------|--------|----------|------------------------------------------|
| `response_type`         | string | Yes      | Must be `code`                           |
| `client_id`             | string | Yes      | UUID of the registered OAuth client      |
| `redirect_uri`          | string | Yes      | Must match a registered redirect URI     |
| `scope`                 | string | No       | Space-separated scopes. Ordinary authorization defaults to the client's configured `allowed_scopes`; incremental authorization preserves the existing grant when omitted and adds only the requested scopes when supplied. Additional scopes include `roles` (RBAC claims) and `groups` (group memberships). |
| `state`                 | string | No       | Opaque value for CSRF protection         |
| `code_challenge`        | string | Yes      | PKCE code challenge (base64url-encoded SHA-256) |
| `code_challenge_method` | string | No       | Must be `S256` if provided               |
| `nonce`                 | string | No       | Value included in ID token for replay protection |
| `include_granted_scopes` | boolean | No | `true` requests additive OAuth scopes and service access, like Google's incremental authorization option |
| `service_access_mode`   | string | No       | `incremental` is the NyxID-specific alias for add-only consent; omission keeps ordinary authorization/review behavior unless `include_granted_scopes=true` |
| `requested_service_ids` | repeated string | No | Exact UserService UUIDs required by an incremental request (maximum 100 entries, deduplicated); requires `include_granted_scopes=true` or `service_access_mode=incremental` |
| `resource`              | repeated string | No | RFC 8707 resources; in incremental mode their services are also required, and they narrow the initial access token rather than the accumulated refresh/binding grant |
| `binding_grant_id`      | string | No       | SHA-256 of an existing binding handle, to update that exact binding; external subject must match, including an absent subject in incremental mode |

Incremental authorization requires a live consent for the current user and client. NyxID signs the existing grant and requested IDs, then asks the user to confirm additions. Existing A/B plus newly approved C/D produces A/B/C/D in the authorization code, refresh token, and broker binding. Existing unrestricted access stays unrestricted; a restricted grant cannot become unrestricted in this mode. Unknown, disabled, or inaccessible new service IDs are rejected. Concurrent grant changes or revocation invalidate stale decisions/codes and require restarting authorization; routine broker refresh-token rotation does not change the grant.

`POST /oauth/par` accepts the same `include_granted_scopes`, `service_access_mode`, and repeated `requested_service_ids` form fields. Callers must start at the authorization/PAR endpoint, not construct a consent page URL or provide a grant snapshot themselves. See [incremental service access and the Aevatar integration contract](site/shared/concepts/oauth-oidc.md#adding-service-access-incrementally).

**Response (200):**

```json
{
  "redirect_url": "https://app.example.com/callback?code=auth_code_here&state=xyz"
}
```

**Errors:**
- `1000 bad_request` -- Unsupported response_type, missing code_challenge, or unsupported method
- `3001 invalid_redirect_uri` -- Redirect URI not registered for this client
- `3002 invalid_scope` -- Requested scope not allowed for this client

**Example:**

```bash
curl -G http://localhost:3001/oauth/authorize \
  -H "Authorization: Bearer <access_token>" \
  --data-urlencode "response_type=code" \
  --data-urlencode "client_id=client-uuid-here" \
  --data-urlencode "redirect_uri=https://app.example.com/callback" \
  --data-urlencode "scope=openid profile email" \
  --data-urlencode "state=random-state-value" \
  --data-urlencode "code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM" \
  --data-urlencode "code_challenge_method=S256"
```

---

#### POST /oauth/token

Token endpoint. Exchanges an authorization code for access, refresh, and ID tokens. Also supports the `refresh_token` grant type, `urn:ietf:params:oauth:grant-type:token-exchange` for delegated access (see [Token Exchange](#token-exchange-delegated-access)), and social token exchange for native mobile apps (see [Social Token Exchange](#social-token-exchange-native-mobile)).

**Auth:** None (client authenticates via `client_id` and optionally `client_secret`)

**Request Body (authorization_code grant):**

| Field           | Type   | Required | Description                              |
|-----------------|--------|----------|------------------------------------------|
| `grant_type`    | string | Yes      | `authorization_code`                     |
| `code`          | string | Yes      | The authorization code                   |
| `redirect_uri`  | string | Yes      | Must match the authorize request         |
| `client_id`     | string | Yes      | UUID of the OAuth client                 |
| `client_secret` | string | No       | Required for confidential clients        |
| `code_verifier` | string | No       | PKCE code verifier (required if PKCE used)|
| `resource`      | repeated string | No | Requested access-token resources within the granted authority; incremental codes default to the authorize request's resources when omitted, while refresh/binding authority retains the accumulated service grant |

**Request Body (refresh_token grant):**

| Field           | Type   | Required | Description                              |
|-----------------|--------|----------|------------------------------------------|
| `grant_type`    | string | Yes      | `refresh_token`                          |
| `refresh_token` | string | Yes      | A valid refresh token                    |

**Response (200):**

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "openid profile email"
}
```

**ID Token Claims:**

| Claim            | Type    | Description                        |
|------------------|---------|------------------------------------|
| `sub`            | string  | User ID (UUID)                     |
| `iss`            | string  | Issuer (matches `JWT_ISSUER`)      |
| `aud`            | string  | Client ID                          |
| `exp`            | integer | Expiration (Unix timestamp)        |
| `iat`            | integer | Issued at (Unix timestamp)         |
| `email`          | string  | User email address                 |
| `email_verified` | boolean | Whether email is verified          |
| `name`           | string  | User display name                  |
| `picture`        | string  | User avatar URL                    |
| `nonce`          | string  | Echoed from authorize request      |

**Errors:**
- `1000 bad_request` -- Missing parameters, unsupported grant_type
- `3000 pkce_verification_failed` -- Code verifier does not match challenge

**Example:**

```bash
curl -X POST http://localhost:3001/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "auth_code_here",
    "redirect_uri": "https://app.example.com/callback",
    "client_id": "client-uuid-here",
    "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
  }'
```

---

#### GET /oauth/userinfo

OpenID Connect UserInfo endpoint. Returns claims about the authenticated user. When the access token's scope includes `roles` or `groups`, the response includes RBAC claims.

**Auth:** Required (Bearer token issued by the `/oauth/token` endpoint)

**Response (200):**

```json
{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "email_verified": true,
  "name": "Jane Doe",
  "picture": "https://example.com/avatar.jpg",
  "roles": ["admin", "editor"],
  "groups": ["engineering"],
  "permissions": ["users:read", "users:write", "content:read", "content:write"]
}
```

The `roles`, `groups`, and `permissions` fields are only present when the corresponding scopes (`roles`, `groups`) were requested during authorization.

**Example:**

```bash
curl http://localhost:3001/oauth/userinfo \
  -H "Authorization: Bearer <access_token>"
```

---

### Token Introspection

#### POST /oauth/introspect

Token introspection endpoint per [RFC 7662](https://tools.ietf.org/html/rfc7662). Validates a token and returns its active status with associated claims. The request body is `application/x-www-form-urlencoded`.

**Auth:** None (client authenticates via `client_id` and `client_secret` in the request body)

**Request Body (form-encoded):**

| Field             | Type   | Required | Description                              |
|-------------------|--------|----------|------------------------------------------|
| `token`           | string | Yes      | The token to introspect                  |
| `token_type_hint` | string | No       | `access_token` or `refresh_token`        |
| `client_id`       | string | Yes      | OAuth client ID                          |
| `client_secret`   | string | No       | OAuth client secret (required for confidential clients) |

**Response (200) -- Active token:**

```json
{
  "active": true,
  "scope": "openid profile email roles",
  "username": "user@example.com",
  "token_type": "access",
  "exp": 1717200000,
  "iat": 1717199100,
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "iss": "nyxid",
  "jti": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "roles": ["admin", "editor"],
  "groups": ["engineering"],
  "permissions": ["users:read", "users:write"]
}
```

**Response (200) -- Inactive/invalid token:**

```json
{
  "active": false
}
```

The endpoint always returns 200. Invalid tokens, expired tokens, revoked tokens, and requests with invalid client credentials all return `{"active": false}`.

**Example:**

```bash
curl -X POST http://localhost:3001/oauth/introspect \
  -d "token=eyJhbGciOiJSUzI1NiIs..." \
  -d "client_id=client-uuid-here" \
  -d "client_secret=client-secret-here"
```

---

### Token Revocation

#### POST /oauth/revoke

Token revocation endpoint per [RFC 7009](https://tools.ietf.org/html/rfc7009). Revokes a token so it can no longer be used. The request body is `application/x-www-form-urlencoded`.

**Auth:** None (client authenticates via `client_id` and `client_secret` in the request body)

**Request Body (form-encoded):**

| Field             | Type   | Required | Description                              |
|-------------------|--------|----------|------------------------------------------|
| `token`           | string | Yes      | The token to revoke                      |
| `token_type_hint` | string | No       | `access_token` or `refresh_token`        |
| `client_id`       | string | Yes      | OAuth client ID                          |
| `client_secret`   | string | No       | OAuth client secret (required for confidential clients) |

**Response:** Always returns `200 OK` with an empty body, per RFC 7009. This applies even if the token is invalid, already revoked, or client authentication fails.

Refresh tokens are revoked in the database (marked `revoked = true`). Access tokens are stateless JWTs and cannot be explicitly revoked; they expire naturally (default: 15 minutes).

**Example:**

```bash
curl -X POST http://localhost:3001/oauth/revoke \
  -d "token=eyJhbGciOiJSUzI1NiIs..." \
  -d "client_id=client-uuid-here" \
  -d "client_secret=client-secret-here"
```

---

### Token Exchange (Delegated Access)

NyxID supports [RFC 8693 OAuth 2.0 Token Exchange](https://tools.ietf.org/html/rfc8693) to enable downstream services to make API calls on behalf of users. This is used when a downstream service (registered as an OIDC client) needs to call NyxID's LLM gateway or proxy endpoints using the user's credentials.

#### POST /oauth/token (token-exchange grant)

Exchange a user's access token for a short-lived delegated access token. The delegated token can be used as a Bearer token at NyxID's proxy and LLM gateway endpoints. Separately, service-issued delegated tokens may carry `account:read` for read-only management parity as described below.

**Auth:** None (client authenticates via `client_id` and `client_secret` in the request body)

**Preconditions:**
1. The downstream service must be registered as a **confidential** OAuth client with `delegation_scopes` configured
2. The user must have an existing consent record for the client (auto-created during OIDC login)
3. The subject token must be a valid, non-expired, non-delegated NyxID access token

**Request Body (form-encoded):**

| Field                | Type   | Required | Description                                                |
|----------------------|--------|----------|------------------------------------------------------------|
| `grant_type`         | string | Yes      | `urn:ietf:params:oauth:grant-type:token-exchange`          |
| `client_id`          | string | Yes      | The downstream service's OAuth client ID                   |
| `client_secret`      | string | Yes      | The downstream service's OAuth client secret               |
| `subject_token`      | string | Yes      | The user's NyxID access token                              |
| `subject_token_type` | string | Yes      | Must be `urn:ietf:params:oauth:token-type:access_token`    |
| `scope`              | string | No       | Requested delegation scopes (default: `llm:proxy`)         |
| `resource`           | string[] | No       | RFC 8707 connected-service resources to include           |
| `allow_all_services` | boolean | Catalog | Explicit service authority posture for `mcp:catalog:read` |
| `allowed_service_ids`| string[] | Catalog | Explicit connected-service IDs for `mcp:catalog:read`    |
| `allow_all_nodes`    | boolean | Catalog | Explicit node authority posture for `mcp:catalog:read`   |
| `allowed_node_ids`   | string[] | Catalog | Explicit node IDs for `mcp:catalog:read`                 |

**Available Delegation Scopes:**

| Scope              | Access                                                          |
|--------------------|-----------------------------------------------------------------|
| `llm:proxy`        | LLM gateway and provider-specific proxy endpoints               |
| `proxy:*`          | All proxy endpoints (`/api/v1/proxy/{service_id}/{*path}`)      |
| `proxy:{service_id}` | A specific service's proxy endpoint                           |
| `llm:status`       | Read-only access to LLM status endpoint                        |
| `mcp:catalog:read` | Read-only connected-service catalog authority; no proxy, management, secret, or effect access |
| `account:read`     | GET-only access to the user's existing management resources, subject to route-class and WebSocket exclusions |

`account:read` is service-issued only. It may be configured on an admin-managed downstream or user-service row, but OAuth clients cannot include it in `delegation_scopes`, request it through RFC 8693 token exchange, or regain it during delegation refresh. The scope preserves each endpoint's existing personal and organization ACLs, never authorizes management writes, and does not permit admin, auth/provisioning, credential-delivery, execution, streaming, or WebSocket route classes.

**Response (200):**

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "llm:proxy"
}
```

**Delegated Token JWT Claims:**

| Claim       | Type    | Description                                        |
|-------------|---------|----------------------------------------------------|
| `sub`       | string  | User ID (the user being acted on behalf of)        |
| `iss`       | string  | NyxID issuer                                       |
| `aud`       | string  | NyxID base URL                                     |
| `exp`       | integer | Expiration (5 minutes from issuance)               |
| `iat`       | integer | Issued at                                          |
| `jti`       | string  | Unique token ID                                    |
| `scope`     | string  | Constrained delegation scopes                      |
| `token_type`| string  | `"access"`                                         |
| `act.sub`   | string  | OAuth client ID of the acting service (RFC 8693)   |
| `client_id` | string  | Receiving OAuth client ID for catalog delegation  |
| `delegated` | boolean | `true` (distinguishes from direct user tokens)     |
| `resources` | string[] | Canonical RFC 8707 resources granted to the token |
| `allow_all_services` / `allowed_service_ids` | boolean / string[] | Explicit connected-service authority for catalog tokens |
| `allow_all_nodes` / `allowed_node_ids` | boolean / string[] | Explicit node authority for catalog tokens and new delegated tokens |

**Errors:**
- `1000 bad_request` -- Missing required parameters, invalid `subject_token_type`, subject token is not an access token, or subject token is itself a delegated token (chained exchange rejected)
- `1001 unauthorized` -- Invalid client credentials or invalid/expired subject token
- `1002 forbidden` -- User has not consented to delegation for this client, or token exchange is not enabled for this client (empty `delegation_scopes`)
- `3002 invalid_scope` -- Requested scope is not in the client's `delegation_scopes`

**Example:**

```bash
curl -X POST http://localhost:3001/oauth/token \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "client_id=downstream-client-id" \
  -d "client_secret=downstream-client-secret" \
  -d "subject_token=eyJhbGciOiJSUzI1NiIs..." \
  -d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "scope=llm:proxy"
```

**Using the Delegated Token:**

```bash
# Use the delegated token to call NyxID's LLM gateway on behalf of the user
curl -X POST http://localhost:3001/api/v1/llm/gateway/v1/chat/completions \
  -H "Authorization: Bearer <delegated_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

**Endpoint Access Restrictions:**

Delegated tokens retain their native proxy, LLM, and refresh access according to scope. A service-issued token with the exact `account:read` scope may also call eligible management `GET` endpoints; management writes, WebSocket upgrades, and the denied route classes described above still return `403 Forbidden`.

| Endpoint Group                                      | Delegated Token Access                              |
|-----------------------------------------------------|-----------------------------------------------------|
| `/api/v1/llm/*`                                     | Allowed by native LLM scopes                        |
| `/api/v1/proxy/{id}/{*path}`                        | Allowed by native proxy scopes                      |
| `/api/v1/delegation/refresh`                        | Allowed for refreshable delegated scopes            |
| `/api/v1/delegation/operation-catalog`              | Allowed only with `mcp:catalog:read`                |
| Eligible management `GET` endpoints                | Allowed only with exact `account:read`              |
| Management writes, upgrades, and denied GET classes | Blocked                                             |

---

#### POST /api/v1/delegation/refresh

Refresh a delegated access token. Issues a new delegation token with the same `act.sub` and scope but a fresh 5-minute TTL. Only accepts delegated tokens -- regular user tokens are rejected with 403.

This endpoint is critical for agentic/long-running workflows where a downstream service needs to make API calls over an extended period.

**Auth:** Required (delegated Bearer token only)

**Request:** No request body. The current delegation token is provided via the `Authorization: Bearer` header.

**Response (200):**

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "llm:proxy"
}
```

**Security:**
- Validates the user still exists and is active
- Validates the user still has active consent for the acting client (prevents indefinite refresh after consent revocation)

**Errors:**
- `1001 unauthorized` -- Invalid/expired token, or user account is inactive or not found
- `1002 forbidden` -- Token is not a delegated token (missing `act.sub`), or user consent has been revoked for the acting client

**Example:**

```bash
# Refresh a delegation token before it expires
curl -X POST http://localhost:3001/api/v1/delegation/refresh \
  -H "Authorization: Bearer <current_delegation_token>"
```

---

#### GET /api/v1/delegation/operation-catalog

Returns the delegated caller's safe, exact-operation discovery view. The
request must use a verified delegated token with `mcp:catalog:read`; service
and node authority comes from the live grant keyed by the token `jti`, and is
never inferred from an unrestricted default.

This endpoint is discovery-only. A caller that also needs to create, observe,
or redeem an exact-service approval must use the **same delegated token with
both independently granted scopes**: `mcp:catalog:read` and `proxy` or
`proxy:*`. Catalog-read alone never grants proxy, generic-proxy, approval, or
other effect authority. The existing approval endpoints intentionally return
403 for a catalog-only token.

**Auth:** Required (delegated Bearer token with `mcp:catalog:read`)

**Response (200):**

```json
{
  "contract_version": "nyxid-delegated-operation-catalog.v2",
  "catalog_digest": "sha256:opaque-admission-token",
  "exact_view_digest": "sha256:exact-caller-visible-view",
  "resolved_at": "2026-08-14T00:00:00Z",
  "authority_expires_at": "2026-08-14T00:05:00Z",
  "services": [
    {
      "user_service_id": "user-service-uuid",
      "catalog_service_id": "catalog-provider-uuid",
      "service_slug": "github",
      "service_name": "GitHub",
      "description": "Connected GitHub service",
      "node_id": null,
      "operations": [
        {
          "endpoint_id": "op_opaque_id",
          "name": "list_repositories",
          "method": "GET",
          "path": "/user/repos",
          "parameters": null,
          "request_body_schema": null,
          "request_content_type": null,
          "request_body_required": false,
          "response": {
            "content_types": ["application/json"],
            "binary_artifact": false
          },
          "risk": "read",
          "supports_idempotency_key": false,
          "endpoint_contract_digest": "sha256:...",
          "operation_generation": 7
        }
      ]
    }
  ],
  "total_services": 1,
  "total_operations": 1
}
```

`exact_view_digest` is the representation validator for the caller-visible
`services` array. Digests use SHA-256 over canonical compact JSON containing
`contract_version: "nyxid-delegated-operation-catalog.v2"` and the returned
`services`; services are sorted by `user_service_id`, operations by
`endpoint_id`, and object keys recursively in lexicographic order. Dynamic
timestamps, totals, and `catalog_digest` are excluded.

The producer-owned `operation_generation`, `risk`, and
`supports_idempotency_key` fields are additive to v2. During the bounded mixed-
replica compatibility window, discovery emits the v2 digest of the same
projection with those three fields omitted. Clients should echo that response
value for compatibility with every replica. A client may instead recompute the
full additive digest by retaining all three fields in the canonical projection;
new replicas accept either value at create and redeem, and during live
revalidation. New rows retain the pre-additive value in the legacy
`exact_view_digest` slot so an old replica can revalidate them, and persist the
full projection in a server-owned `exact_view_digest_binding` slot that new
replicas also enforce. This catches additive policy changes written by an old
replica even though that writer cannot bump `operation_generation`. This lets
existing clients and old and new NyxID replicas coexist during an ordinary
rolling deploy.

Each service also carries the producer-owned `catalog_service_id` used to
resolve its catalog provider. This field is included in `exact_view_digest` and
is nullable: a custom user service with typed operations has no catalog
provider, so its value is `null` and `user_service_id` is its canonical
identity.

`operation_generation` is the positive, producer-owned revision of a durable
`ServiceEndpoint`. It starts at 1, increments when the endpoint contract or
active state changes, remains stable across no-op reconciliation, and is paired
with the opaque `endpoint_id` so delete/recreate cannot form an ABA identity.
Startup backfill assigns 1 only to legacy rows where the generation field is
missing. Operations parsed from an instance-mounted `openapi_spec_url` have no
durable producer row; they remain discoverable with `operation_generation:
null`, persist `producer_generation_bound: false`, and use
`endpoint_contract_digest` as their shape fence.

`catalog_digest` remains the pre-existing broad approval fence. For wire
compatibility with #1424 (commit `d1a042c2`), it is exactly
`mcp_service::operation_catalog_digest` over the complete scoped catalog. It
also includes catalog services that this facade omits (platform and generic
rows), plus descriptor metadata such as operation descriptions and
`recommended_skills`. Exact approval callers should send both digest fields at
create and redeem when the target is in the exact view. Consumers must treat
both values as opaque rather than substituting fetch time or a local counter.

Exact-service eligibility and digest applicability are:

| Requester | Target in exact view | `exact_view_digest` at create | Result | Persisted fence |
|---|---:|---|---|---|
| Delegated | Yes | Matching | Accepted | Server-resolved digest |
| Delegated | Yes | Omitted | `400 exact_view_digest_required` | No write |
| Nondelegated | Yes | Omitted or matching | Accepted | Server-resolved digest |
| Delegated | No | Omitted | `404 exact_operation_not_in_exact_view` | No write |
| Delegated | No | Supplied | `404 exact_operation_not_in_exact_view` | No write |
| Nondelegated | No | Omitted | Accepted | `null` / omitted |
| Nondelegated | No | Supplied | `400 exact_view_digest_not_applicable` | No write |

Delegated callers are additionally required to carry the `mcp:catalog:read`
scope on all three exact-service routes (create, status, redeem). A delegated
token without it returns `403 delegated_catalog_scope_required` before any
catalog resolution or persistence. Such tokens cannot obtain a delegated
exact-view digest in the first place, because discovery requires the same
scope, and they are not covered by the live catalog-grant revalidation that
`mcp:catalog:read` tokens undergo on every request.

A mismatched in-view digest returns the existing
`exact_service_exact_view_digest_drift` conflict, and an empty supplied value is
rejected as a bad request.

Create never requires or rejects `operation_generation`. NyxID resolves and
persists the live producer generation for a durable endpoint regardless of
caller input; a supplied mismatch is debug telemetry only. Freshness at create
is already established by `catalog_digest`, `exact_view_digest`, and
`endpoint_contract_digest`. The stored producer value is used to detect drift
between create and redeem. Instance-spec operations persist generation `0` with
`producer_generation_bound: false`, so observe and redeem skip only the
generation comparison while retaining every digest fence. Clients redeem with
the value returned by create/status.

At redeem the fence follows the same split. For **delegated** callers an
omitted `exact_view_digest` is rejected with `400 exact_view_digest_required`
before the request is loaded or claimed; a supplied empty or mismatched digest
returns `exact_service_redemption_conflict`. For **nondelegated** callers
omission remains accepted, and the server still re-resolves the catalog and
revalidates the digest persisted in the approval binding.

Redeem and observe also revalidate a producer-owned **execution-authority v2
binding** persisted as `{ projection_version, digest }` at create. It binds the resolved
destination URL, auth method, credential identity plus `credential_epoch`,
identity-injection config, default headers, proxy operation policy, configured
node-binding set, `service_category`, `requires_user_credential`, and a nested
digest of the execution-relevant `token_exchange_config`. A mismatch returns
HTTP 200 with `state: "drifted"` and
`failure_code: "execution_authority_drift"` and does not dispatch downstream.
Catalog, shape, or producer-generation drift uses `catalog_drift`.
New rows also store the real v1 projection digest in the legacy
`execution_authority_digest` slot. Old replicas validate that slot exactly as
before, while new replicas validate the v2 binding. For main-era rows with no
versioned binding and a v1 digest, new replicas recompute and compare the live
v1 projection. A versioned v1 binding is handled the same way. Rows with neither
field predate authority digests and skip this one gate within their approval
expiry. `execution_authority_version_unsupported` is reserved for genuinely
unknown future projection versions.

Observe and redeem use one ordered live evaluator: catalog and exact-generation
checks, then approval-policy revalidation, then a read-only execution-authority
snapshot. Observe does not claim the request, materialize credentials, or write
a redemption, so content-addressed A-to-B-to-A configuration can recover from
`drifted` back to `approved`. Redeem checks only persisted state before its
atomic claim, runs the same evaluator after the claim, and durably records any
terminal drift/revocation/failure. Only after all read-only gates pass may it
materialize or refresh credentials; the materialized execution authority is
digested and compared once more before the provider effect. The claim predicate
atomically requires `status=approved`, no prior redemption, and
`expires_at > admitted_at`. If a concurrent deny/expiry/redemption wins, redeem
reloads and returns that persisted state; it reads a replay receipt only when a
redemption actually exists.

Buffered exact execution has a 10-minute deadline. Because a timed-out request
may already have committed at the provider, timeout is terminal
`failed/provider_outcome_unknown` and is never automatically replayed. The same
terminal is atomically recovered on a later redeem retry when an `executing`
claim is older than 15 minutes, covering a process crash or failed MongoDB
receipt write while preserving at-most-once dispatch.

| Redeem / observe outcome | `state` | `failure_code` | Downstream effect |
|---|---|---|---|
| Catalog / exact-view / operation identity changed | `drifted` | `catalog_drift` | None |
| Destination, credential identity/epoch, injection, headers, policy, or configured node set changed | `drifted` | `execution_authority_drift` | None |
| Unknown future authority projection | `drifted` | `execution_authority_version_unsupported` | None |
| Selector gone / out of scope | `revoked` | `selector_revoked` | None |
| Direct DNS/connect/TLS handshake or request-build failure | `failed` | `provider_unreachable` | None; terminal request may be recreated only with a new effect key |
| In-flight request failure, effect timeout, response-body/decode/stream failure, or stale `executing` recovery | `failed` | `provider_outcome_unknown` | Never replayed; reconcile provider state |
| Background OAuth token refresh (epoch unchanged) | `redeemed` | omitted | Exactly one |
| URL changed away and back before redeem (ABA) | `redeemed` | omitted | Exactly one |

Legacy and instance-spec approval rows without
`producer_generation_bound: true` skip only the producer-generation
comparison. Main-era v1 authority digests remain executable authority for the
v1 field set, while new rows carry both the real v1 digest and the stronger v2
binding. This makes mixed v1/v2 create, observe, redeem, and rollback safe.
Create keeps the existing
`nyxid-exact-approval-request.v1` identity but derives its generation from the
producer. A semantic pre-upgrade row for the same requester, operation and
idempotency key is detected across pending and terminal states and returns
`exact_service_request_conflict`, preventing a second approval/effect identity.
The atomic fence is the partial unique MongoDB index
`exact_service_semantic_effect_unique` over `(requester_type, requester_id,
exact_service.actor_user_id, exact_service.endpoint_id,
exact_service.effect_idempotency_key)`; producer generation is deliberately not
part of this effect identity. This closes the interval between the semantic
precheck and insert when old and new pods overlap. A losing new pod returns the
typed conflict. A pre-upgrade pod may surface its older database-error response,
but it still cannot create a duplicate effect.

Before first installing or repairing this index, startup runs a bounded
duplicate preflight. If duplicates already exist, or a duplicate write races
the index build, startup logs the remediation, leaves the unique index absent,
persists an active `exact_service_semantic_effect_index` startup diagnostic,
and continues boot. The admin Integrity page surfaces the diagnostic. The
service-level semantic pre-insert check and legacy-replay rejection remain the
guard until an operator resolves the data and restarts. Pause exact-approval
creates and use the following aggregation to enumerate every conflicting group:

```javascript
db.approval_requests.aggregate([
  { $match: { "exact_service.effect_idempotency_key": { $type: "string" } } },
  { $group: {
      _id: {
        requester_type: "$requester_type",
        requester_id: "$requester_id",
        actor_user_id: "$exact_service.actor_user_id",
        endpoint_id: "$exact_service.endpoint_id",
        effect_idempotency_key: "$exact_service.effect_idempotency_key"
      },
      sample_request_id: { $first: "$_id" },
      count: { $sum: 1 }
  } },
  { $match: { count: { $gt: 1 } } }
])
```

Inspect approval decisions, redemption receipts, and downstream-effect evidence
for each group. Reconcile it to one authoritative request only through an audited
operator migration, then restart to build the unique index. Never bulk-delete the
duplicates: a terminal row may be the only durable receipt for an executed effect.

Delegated callers may create, observe, or redeem an exact-service approval only
for a service and operation present in the exact projection returned by
discovery. Nondelegated callers retain the shipped generic-proxy approval
capability, but those out-of-view approvals are not bound to the digest of an
unrelated exact projection.

The response excludes platform fallbacks, generic proxy services, invalid or
empty contracts, unavailable services, credentials, tokens, headers, hashes,
raw provider responses, and arbitrary request bodies. The route performs no
writes, connected-provider invocation, proxy execution, approval mutation, or
credential mutation. This is a database/effect read-only guarantee, not
process-state purity: catalog resolution may perform a hardened, cached,
DNS-pinned outbound fetch of a user-mounted OpenAPI document and update the
process-wide documentation cache when the canonical loader requires one.

An empty service/node authority (`allow_all_*: false` with an empty list) is a
valid deny-all grant and returns `200` with an empty catalog. Unknown or stale
service/node IDs never widen to unrestricted authority; token exchange or live
grant validation rejects them, and deletion after grant issuance remains
restricted rather than falling back to allow-all.

---

#### MCP Delegation Token Injection

When NyxID proxies an MCP tool call or REST proxy request to a downstream service that has `inject_delegation_token: true`, it automatically generates and injects a delegation token as the `X-NyxID-Delegation-Token` header.

This allows the downstream service to use the token as a Bearer token when calling back to NyxID's API endpoints (e.g., LLM gateway) on behalf of the user.

**Injected Header:**

| Header                          | Value                                    |
|---------------------------------|------------------------------------------|
| `X-NyxID-Delegation-Token`     | Short-lived delegated NyxID access JWT   |

**MCP-Injected Token Properties:**

| Property   | Value                                                         |
|------------|---------------------------------------------------------------|
| TTL        | 5 minutes (refreshable via `POST /api/v1/delegation/refresh`) |
| Scope      | Configurable per-service via `delegation_token_scope` (default: `llm:proxy`) |
| `act.sub`  | Service slug of the downstream service                        |
| `delegated`| `true`                                                        |

**Configuration (on the downstream service):**

| Field                      | Type    | Default      | Description                                  |
|----------------------------|---------|--------------|----------------------------------------------|
| `inject_delegation_token`  | boolean | `false`      | Whether to inject delegation tokens          |
| `delegation_token_scope`   | string  | `"llm:proxy"`| Space-separated scopes for the injected token|

Service-issued delegation scopes may include `llm:proxy`, `proxy:*`, `llm:status`,
`account:read`, and `sandbox:execute`. OAuth-client token exchange intentionally
uses a narrower allowlist and does not gain `account:read` or `sandbox:execute`.

**Downstream Service Usage Example (Python):**

```python
from flask import request
import requests

@app.route("/api/analyze", methods=["POST"])
def analyze():
    delegation_token = request.headers.get("X-NyxID-Delegation-Token")
    if not delegation_token:
        return {"error": "No delegation token"}, 400

    # Call NyxID's LLM gateway on behalf of the user
    response = requests.post(
        "https://nyx.example.com/api/v1/llm/gateway/v1/chat/completions",
        headers={
            "Authorization": f"Bearer {delegation_token}",
            "Content-Type": "application/json",
        },
        json={
            "model": "gpt-4o",
            "messages": [{"role": "user", "content": "Analyze this data..."}],
        },
    )
    return response.json()
```

---

### Social Token Exchange (Native Mobile)

NyxID supports exchanging external provider tokens (Google ID tokens, GitHub access tokens) for full NyxID token sets via the existing [RFC 8693 Token Exchange](https://tools.ietf.org/html/rfc8693) endpoint. This enables mobile apps using native SDKs (Google Sign-In, Sign in with GitHub) to authenticate users without browser redirects.

The social token exchange flow is distinguished from the [delegated access flow](#token-exchange-delegated-access) by the `provider` hint and provider-specific `subject_token_type`:
- `provider` omitted + `subject_token_type=urn:ietf:params:oauth:token-type:access_token` -- Delegated access (existing flow, unchanged)
- `provider=google` + `subject_token_type=urn:ietf:params:oauth:token-type:id_token` -- Google social token exchange
- `provider=github` + `subject_token_type=urn:ietf:params:oauth:token-type:access_token` -- GitHub social token exchange

#### POST /oauth/token (social token exchange grant)

Exchange a Google ID token or GitHub access token for a full NyxID token set (access token, refresh token, ID token). If the user does not exist, a new account is created automatically (same logic as web-based social login).

**Auth:** None (client authenticates via `client_id` and optionally `client_secret` in the request body)

**Request Body (form-encoded):**

| Field                | Type   | Required    | Description                                                |
|----------------------|--------|-------------|------------------------------------------------------------|
| `grant_type`         | string | Yes         | `urn:ietf:params:oauth:grant-type:token-exchange`          |
| `subject_token`      | string | Yes         | The external provider token (Google JWT or GitHub access token) |
| `subject_token_type` | string | Yes         | `urn:ietf:params:oauth:token-type:id_token` (Google) or `urn:ietf:params:oauth:token-type:access_token` (GitHub) |
| `client_id`          | string | Yes         | NyxID OAuth client ID                                      |
| `client_secret`      | string | Conditional | Required for confidential clients; omit for public clients |
| `provider`           | string | Yes         | Provider hint: `"google"` or `"github"`                    |

**Response (200):**

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "openid profile email",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}
```

**Errors:**
- `1000 bad_request` -- Missing required parameters (`subject_token`, `subject_token_type`, `provider`)
- `1001 unauthorized` -- Invalid client credentials
- `6000 social_auth_failed` -- Provider API call failed (e.g., GitHub API unreachable)
- `6001 social_auth_conflict` -- Provider identity could not be linked because it is already reserved by another account
- `6002 social_auth_no_email` -- No verified email returned by provider
- `6003 social_auth_deactivated` -- Matched user account is deactivated
- `6004 external_token_invalid` -- External token verification failed (expired, bad signature, wrong audience, unverified email)
- `6005 external_provider_not_configured` -- Provider not configured on the server (e.g., missing `GOOGLE_CLIENT_ID` or `GITHUB_CLIENT_ID`/`GITHUB_CLIENT_SECRET`)

**Example (Google ID token):**

```bash
curl -X POST http://localhost:3001/oauth/token \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=eyJhbGciOiJSUzI1NiIs..." \
  -d "subject_token_type=urn:ietf:params:oauth:token-type:id_token" \
  -d "client_id=your-nyxid-client-id" \
  -d "provider=google"
```

**Example (GitHub access token):**

```bash
curl -X POST http://localhost:3001/oauth/token \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=gho_xxxxxxxxxxxxxxxxxxxx" \
  -d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "client_id=your-nyxid-client-id" \
  -d "provider=github"
```

**Provider Token Verification:**

| Provider | Token Type     | Verification Method                                           |
|----------|----------------|---------------------------------------------------------------|
| Google   | JWT (RS256)    | JWKS signature verification against `googleapis.com/oauth2/v3/certs`; validates `iss`, `aud`, `exp`, `email_verified`, and `iat` freshness (max 10 min) |
| GitHub   | Opaque token   | App-bound token verification via `POST https://api.github.com/applications/{client_id}/token` (using configured `GITHUB_CLIENT_ID`/`GITHUB_CLIENT_SECRET`), then profile lookup via `GET /user` + `GET /user/emails` |

**User Matching:**

The same account linking logic as web-based social login applies:

1. **Returning user** -- If a user with the same provider + provider ID exists, log them in
2. **Email linking** -- If a user with the same verified email exists, link or re-link the social identity to that account
3. **New user** -- If no match, create a new user with `email_verified = true`

**Security Notes:**
- Google ID tokens are verified cryptographically (RS256 JWKS) -- NyxID never sends Google tokens to a third party
- GitHub tokens are first verified against NyxID's configured GitHub OAuth app, then profile data is fetched from GitHub APIs
- JWKS keys are cached with TTL (default 1 hour, respects `Cache-Control: max-age`) to minimize external calls
- The `provider` parameter is required (not auto-detected) to avoid issuer guessing attacks
- All exchanges are audit-logged with provider, client ID, and result
- Existing rate limiting on `POST /oauth/token` applies

**Mobile SDK Integration:**

To use social token exchange from a mobile app:

1. **Register an OAuth client** in NyxID (can be a public client for mobile -- no `client_secret` required)
2. **Authenticate with the native SDK** in your mobile app:
   - **iOS/Android (Google):** Use [Google Sign-In SDK](https://developers.google.com/identity/sign-in) to obtain a Google ID token
   - **iOS/Android (GitHub):** Use GitHub OAuth (via ASWebAuthenticationSession / Chrome Custom Tabs) to obtain a GitHub access token
3. **Exchange the token** by calling `POST /oauth/token` with the parameters above
4. **Store the NyxID tokens** securely (iOS Keychain / Android Keystore) and use the access token for subsequent API calls
5. **Refresh when expired** using the standard `refresh_token` grant at `POST /oauth/token`

```swift
// iOS (Swift) example
let url = URL(string: "https://auth.example.com/oauth/token")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")

let body = [
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token": googleIdToken,
    "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
    "client_id": "your-nyxid-client-id",
    "provider": "google"
].map { "\($0.key)=\($0.value)" }.joined(separator: "&")

request.httpBody = body.data(using: .utf8)
let (data, _) = try await URLSession.shared.data(for: request)
```

```kotlin
// Android (Kotlin) example
val client = OkHttpClient()
val body = FormBody.Builder()
    .add("grant_type", "urn:ietf:params:oauth:grant-type:token-exchange")
    .add("subject_token", googleIdToken)
    .add("subject_token_type", "urn:ietf:params:oauth:token-type:id_token")
    .add("client_id", "your-nyxid-client-id")
    .add("provider", "google")
    .build()

val request = Request.Builder()
    .url("https://auth.example.com/oauth/token")
    .post(body)
    .build()

val response = client.newCall(request).execute()
```

---

### User Consents

#### GET /api/v1/users/me/consents

List all OAuth consents the current user has granted to third-party applications.

**Auth:** Required

**Response (200):**

```json
{
  "consents": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "client_id": "client-uuid-here",
      "client_name": "My Web App",
      "scopes": "openid profile email",
      "granted_at": "2025-06-01T10:00:00+00:00",
      "expires_at": null
    }
  ]
}
```

**Example:**

```bash
curl http://localhost:3001/api/v1/users/me/consents \
  -H "Authorization: Bearer <access_token>"
```

---

#### DELETE /api/v1/users/me/consents/{client_id}

Revoke an OAuth consent for a specific client. The user will be prompted to re-authorize on the next OAuth flow with this client.

**Auth:** Required

**Path Parameters:**

| Parameter   | Type   | Description             |
|-------------|--------|-------------------------|
| `client_id` | string | The OAuth client ID     |

**Response (200):**

```json
{
  "message": "Consent revoked"
}
```

**Errors:**
- `1003 not_found` -- No consent found for this client

**Example:**

```bash
curl -X DELETE http://localhost:3001/api/v1/users/me/consents/client-uuid-here \
  -H "Authorization: Bearer <access_token>"
```

---

### OIDC Discovery

These endpoints are public and do not require authentication. They allow relying parties (downstream services using OIDC) to automatically discover NyxID's provider configuration and verify JWT signatures.

#### GET /.well-known/openid-configuration

Returns the OpenID Connect Provider metadata document. Relying parties use this to auto-configure authorization, token, and userinfo endpoint URLs.

**Auth:** None

**Response (200):**

```json
{
  "issuer": "nyxid",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "userinfo_endpoint": "https://auth.example.com/oauth/userinfo",
  "jwks_uri": "https://auth.example.com/.well-known/jwks.json",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "scopes_supported": ["openid", "profile", "email"],
  "claims_supported": [
    "sub", "iss", "aud", "exp", "iat",
    "email", "email_verified", "name", "picture", "nonce"
  ],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_post", "none"]
}
```

**Example:**

```bash
curl https://auth.example.com/.well-known/openid-configuration
```

---

#### GET /.well-known/jwks.json

Returns the JSON Web Key Set (JWKS) containing the public key(s) used to sign JWTs. Relying parties use this to verify token signatures without needing a shared secret.

**Auth:** None

**Response (200):**

```json
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "n": "<base64url-encoded modulus>",
      "e": "AQAB",
      "kid": "<key-id>"
    }
  ]
}
```

**Example:**

```bash
curl https://auth.example.com/.well-known/jwks.json
```

---

### MFA (Multi-Factor Authentication)

#### POST /api/v1/auth/mfa/setup

Begin TOTP MFA enrollment. Returns a TOTP secret and a QR code provisioning URL. If a previous unverified TOTP factor exists from an abandoned enrollment attempt, it is soft-deactivated and a fresh secret is minted (idempotent re-enrollment). A *verified* factor still 409s — disable MFA first via `POST /api/v1/auth/mfa/disable`.

**Auth:** Required

**Response (200):**

```json
{
  "factor_id": "<uuid>",
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_code_url": "otpauth://totp/NyxID:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=NyxID"
}
```

**Errors:**
- `1004 conflict` -- A *verified* TOTP factor already exists; disable it first

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/auth/mfa/setup \
  -H "Authorization: Bearer <access_token>"
```

---

#### POST /api/v1/auth/mfa/confirm

Complete MFA enrollment by verifying a TOTP code. On success, MFA is enabled on the user account and recovery codes are returned. (Pre-#506 this endpoint was incorrectly documented as `/api/v1/mfa/verify-setup` which never existed; the canonical route is `/api/v1/auth/mfa/confirm`.)

**Auth:** Required

**Request Body:**

| Field  | Type   | Required | Description                           |
|--------|--------|----------|---------------------------------------|
| `code` | string | Yes      | 6-digit TOTP code from authenticator  |

```json
{
  "code": "123456"
}
```

**Response (200):**

```json
{
  "message": "MFA enabled successfully",
  "recovery_codes": [
    "ABCD-1234-EFGH",
    "IJKL-5678-MNOP",
    "QRST-9012-UVWX"
  ]
}
```

**Errors:**
- `2000 authentication_failed` -- Invalid TOTP code
- `1003 not_found` -- No pending MFA factor found

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/auth/mfa/confirm \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'
```

---

### Provider-linked service configuration

Both provider/service endpoints require admin access:
`GET /api/v1/providers/{provider_id}/services` lists canonical links and legacy
provider requirements. `PUT /api/v1/providers/{provider_id}/services/{service_id}` links an existing catalog
service; `POST /api/v1/services` also accepts `provider_config_id` for atomic
creation/linking. A service already linked to another provider is not rebound.
Direct-auth services retain their authentication method without adding provider
requirements.

Service updates accept a write-only `credential` (blank preserves), `platform_key`,
credential-class billing lanes, and `proxy_operation_policy`. Omitted policy
preserves; null clears; `{ "rules": [] }` denies every endpoint. Rules contain
an HTTP `method` and absolute `path_template`, and apply to all service bindings.
New shared keys default disabled/restricted. Admin response
`credential_configured` is true/false after authorized inspection, or null when
unreadable; non-admin responses return null without inspecting the credential.

Platform Operations routes and its three named MCP operation tools are removed.
See [Service configuration and vendor retirement](SERVICE_CONFIGURATION.md) for
linking, access, billing, and migration behavior, and [Admin form save
behavior](ADMIN_FORM_SAFETY.md) for sparse updates and confirmation.

### Admin

All admin endpoints require the authenticated user to have `is_admin = true`. Admin endpoints include self-protection: admins cannot change their own role, disable themselves, or delete themselves.

#### PATCH /api/v1/admin/feature-flags/{flag_key}/metadata

Update only the supplied metadata fields for a registered feature flag.

**Auth:** Admin

| Field | Type | Required | Behavior |
| --- | --- | --- | --- |
| `description` | string/null | No | Omission preserves; null or trimmed blank clears the custom description and displays the code-declared fallback. |
| `owner` | string/null | No | Omission preserves; null or trimmed blank clears the owner. |

Unknown fields are rejected. An empty object leaves the metadata unchanged.
An unknown flag key returns a bad-request error.

**Response (200):** The saved metadata descriptor: `key`, effective `description`,
`code_description`, nullable `custom_description`, nullable `owner`, and nullable
`metadata_updated_at` / `metadata_updated_by`.

For example, `{"owner":"Identity team"}` changes only the owner. The existing
`PUT` route at this path keeps its replacement contract: omitted fields are
cleared. Clients that need sparse updates should use `PATCH`.

---

#### GET /api/v1/admin/users

List all users with pagination and optional email search.

**Auth:** Admin

**Query Parameters:**

| Parameter  | Type    | Default | Description                          |
|------------|---------|---------|--------------------------------------|
| `page`     | integer | `1`     | Page number (1-indexed)              |
| `per_page` | integer | `50`    | Items per page (max 100)             |
| `search`   | string  | --      | Case-insensitive email search filter |

**Response (200):**

```json
{
  "users": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "display_name": "Jane Doe",
      "avatar_url": null,
      "email_verified": true,
      "is_active": true,
      "is_admin": false,
      "mfa_enabled": true,
      "created_at": "2025-01-15T10:30:00+00:00",
      "last_login_at": "2025-06-01T14:22:00+00:00"
    }
  ],
  "total": 142,
  "page": 1,
  "per_page": 50
}
```

**Example:**

```bash
# List users
curl "http://localhost:3001/api/v1/admin/users?page=1&per_page=25" \
  -H "Authorization: Bearer <admin_access_token>"

# Search by email
curl "http://localhost:3001/api/v1/admin/users?search=jane" \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### POST /api/v1/admin/users

Create a new user. Admin-created accounts are pre-verified (`email_verified: true`) and active (`is_active: true`).

**Auth:** Admin

**Request Body:**

| Field          | Type   | Required | Description                                      |
|----------------|--------|----------|--------------------------------------------------|
| `email`        | string | Yes      | User email address                               |
| `password`     | string | Yes      | Password (8-128 characters)                      |
| `display_name` | string | No       | Display name (max 200 characters)                |
| `role`         | string | Yes      | `"admin"` or `"user"`                            |

**Response (200):**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "newuser@example.com",
  "display_name": "Jane Doe",
  "is_admin": false,
  "is_active": true,
  "email_verified": true,
  "created_at": "2025-06-15T10:30:00+00:00",
  "message": "User created successfully"
}
```

**Errors:**
- `1004 conflict` -- Email already in use
- `1008 validation_error` -- Invalid email, password too short/long, or invalid role

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/admin/users \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "securepassword123",
    "display_name": "Jane Doe",
    "role": "user"
  }'
```

---

#### GET /api/v1/admin/users/{user_id}

Get detailed information about a specific user.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `user_id` | UUID | The user ID |

**Response (200):**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "display_name": "Jane Doe",
  "avatar_url": null,
  "email_verified": true,
  "is_active": true,
  "is_admin": false,
  "mfa_enabled": true,
  "created_at": "2025-01-15T10:30:00+00:00",
  "last_login_at": "2025-06-01T14:22:00+00:00"
}
```

**Errors:**
- `1003 not_found` -- User does not exist

**Example:**

```bash
curl http://localhost:3001/api/v1/admin/users/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### PUT /api/v1/admin/users/{user_id}

Edit a user's profile fields. Only provided fields are updated.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `user_id` | UUID | The user ID |

**Request Body:**

| Field          | Type   | Required | Description                                |
|----------------|--------|----------|--------------------------------------------|
| `display_name` | string | No       | New display name (max 200 chars)           |
| `email`        | string | No       | New email (validated, unique check)        |
| `avatar_url`   | string | No       | New avatar URL (must use https://, max 2048 chars) |

```json
{
  "display_name": "Jane Smith",
  "email": "jane.smith@example.com"
}
```

**Response (200):**

Returns the updated user object (same shape as GET response).

**Errors:**
- `1003 not_found` -- User does not exist
- `1008 validation_error` -- Invalid email format, email already in use, display name too long, or invalid avatar URL

**Example:**

```bash
curl -X PUT http://localhost:3001/api/v1/admin/users/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "Jane Smith"}'
```

---

#### PATCH /api/v1/admin/users/{user_id}/role

Toggle admin role for a user. Self-protection: an admin cannot change their own role.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `user_id` | UUID | The user ID |

**Request Body:**

| Field      | Type    | Required | Description           |
|------------|---------|----------|-----------------------|
| `is_admin` | boolean | Yes      | New admin role status |

```json
{
  "is_admin": true
}
```

**Response (200):**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "is_admin": true,
  "message": "User admin role updated"
}
```

**Errors:**
- `1003 not_found` -- User does not exist
- `1008 validation_error` -- Cannot change your own admin role

**Example:**

```bash
curl -X PATCH http://localhost:3001/api/v1/admin/users/550e8400-e29b-41d4-a716-446655440000/role \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"is_admin": true}'
```

---

#### PATCH /api/v1/admin/users/{user_id}/status

Enable or disable a user account. Self-protection: an admin cannot change their own status. When disabling a user, all their sessions are revoked, all refresh tokens are invalidated, and all API keys are deactivated, effectively locking them out immediately (except for any in-flight JWT access tokens, which expire within 15 minutes).

**Auth:** Admin

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `user_id` | UUID | The user ID |

**Request Body:**

| Field       | Type    | Required | Description               |
|-------------|---------|----------|---------------------------|
| `is_active` | boolean | Yes      | New active status         |

```json
{
  "is_active": false
}
```

**Response (200):**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "is_active": false,
  "message": "User status updated"
}
```

**Errors:**
- `1003 not_found` -- User does not exist
- `1008 validation_error` -- Cannot change your own active status

**Example:**

```bash
curl -X PATCH http://localhost:3001/api/v1/admin/users/550e8400-e29b-41d4-a716-446655440000/status \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'
```

---

#### POST /api/v1/admin/users/{user_id}/reset-password

Force a password reset for a user. Generates a reset token and revokes all existing sessions. Does not work for social login only accounts (no password set).

**Auth:** Admin

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `user_id` | UUID | The user ID |

**Response (200):**

```json
{
  "message": "Password reset initiated"
}
```

**Errors:**
- `1000 bad_request` -- User has no password (social login only)
- `1003 not_found` -- User does not exist

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/admin/users/550e8400-e29b-41d4-a716-446655440000/reset-password \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### DELETE /api/v1/admin/users/{user_id}

Delete a user and cascade-delete all related data. Self-protection: an admin cannot delete themselves. Audit log entries referencing the deleted user are preserved (orphaned reference).

**Cascade delete** removes documents from 8 collections:
- `sessions`
- `refresh_tokens`
- `api_keys`
- `user_service_connections`
- `user_provider_tokens`
- `mfa_factors`
- `authorization_codes`
- `oauth_states`

The deletion follows a two-phase approach: the user is first marked inactive (preventing authentication during cleanup), then related documents are deleted, and finally the user document itself is removed.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `user_id` | UUID | The user ID |

**Response (200):**

```json
{
  "message": "User deleted"
}
```

**Errors:**
- `1003 not_found` -- User does not exist
- `1008 validation_error` -- Cannot delete yourself

**Example:**

```bash
curl -X DELETE http://localhost:3001/api/v1/admin/users/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### PATCH /api/v1/admin/users/{user_id}/verify-email

Manually verify a user's email address. Clears any pending verification token.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `user_id` | UUID | The user ID |

**Response (200):**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email_verified": true,
  "message": "Email verified"
}
```

**Errors:**
- `1000 bad_request` -- Email already verified
- `1003 not_found` -- User does not exist

**Example:**

```bash
curl -X PATCH http://localhost:3001/api/v1/admin/users/550e8400-e29b-41d4-a716-446655440000/verify-email \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### GET /api/v1/admin/users/{user_id}/sessions

List all sessions for a user (including revoked and expired), sorted by creation time descending.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `user_id` | UUID | The user ID |

**Response (200):**

```json
{
  "sessions": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "ip_address": "203.0.113.42",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
      "created_at": "2025-06-01T14:22:00+00:00",
      "expires_at": "2025-07-01T14:22:00+00:00",
      "last_active_at": "2025-06-01T15:00:00+00:00",
      "revoked": false
    }
  ],
  "total": 3
}
```

**Errors:**
- `1003 not_found` -- User does not exist

**Example:**

```bash
curl http://localhost:3001/api/v1/admin/users/550e8400-e29b-41d4-a716-446655440000/sessions \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### DELETE /api/v1/admin/users/{user_id}/sessions

Revoke all active sessions and refresh tokens for a user, effectively logging them out of all devices.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `user_id` | UUID | The user ID |

**Response (200):**

```json
{
  "revoked_count": 3,
  "message": "All sessions revoked"
}
```

**Errors:**
- `1003 not_found` -- User does not exist

**Example:**

```bash
curl -X DELETE http://localhost:3001/api/v1/admin/users/550e8400-e29b-41d4-a716-446655440000/sessions \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### GET /api/v1/admin/audit-log

Query the audit log with server-side pagination, sorting, scoped search, and filtering. Entries default to reverse chronological order.

**Auth:** Admin or operator

**Query Parameters:**

| Parameter        | Type    | Default       | Description                                                                                     |
|------------------|---------|---------------|-------------------------------------------------------------------------------------------------|
| `page`           | integer | `1`           | Page number (1-indexed)                                                                          |
| `per_page`       | integer | `50`          | Items per page (1--100)                                                                          |
| `sort`           | string  | `-created_at` | `created_at`, `event_type`, `api_key_name`, `api_key_id`, `user_id`, `ip_address`, `user_agent`, or `status`; prefix with `-` for descending |
| `search`         | string  | --            | Case-insensitive `contains` across event type, user ID, API key ID/name, IP, User-Agent, and entry ID (max 256 chars) |
| `search_filters` | string  | --            | Field-scoped search as JSON: `[{"field":"user_id","values":["..."]}]`. Fields: `event_type`, `user_id`, `api_key` (spans key ID and name), `ip_address`, `user_agent`. Max 5 groups, 8 values per group, 32 values overall |
| `event_type`     | string  | --            | Comma-separated event types, matched exactly (max 32)                                            |
| `custom_filters` | string  | --            | Free text OR'd into a filter, as JSON: `{"event_type":["mfa"]}`. Only `event_type` accepts text  |
| `status`         | string  | --            | Comma-separated response-status buckets: `2xx`, `3xx`, `4xx`, `5xx`, `none` (no `response_status` recorded) |
| `actor`          | string  | --            | Comma-separated: `user` (session), `agent` (API key), `anonymous`                                |
| `created_dates`  | string  | --            | Comma-separated `YYYY-MM-DD` days (UTC, max 32). Cannot combine with `created_from` / `created_to` |
| `created_from`   | string  | --            | Inclusive `YYYY-MM-DD` lower bound (UTC)                                                          |
| `created_to`     | string  | --            | Inclusive `YYYY-MM-DD` upper bound (UTC)                                                          |
| `user_id`        | string  | --            | Legacy exact-match filter on the acting user ID                                                   |
| `api_key_id`     | string  | --            | Legacy exact-match filter on the agent API key ID                                                 |

**Response (200):**

`filter_options` describes the controls the server accepts, so clients never hardcode a domain it would reject. `event_type` options are discovered from the data (capped at 200); anything past the cap stays reachable through `custom_filters`.

```json
{
  "entries": [
    {
      "id": "entry-uuid-here",
      "seq": 123,
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "api_key_id": null,
      "api_key_name": null,
      "event_type": "admin.user.deleted",
      "event_data": {
        "target_user_id": "660e8400-e29b-41d4-a716-446655440000",
        "target_email": "deleted-user@example.com"
      },
      "ip_address": "203.0.113.42",
      "user_agent": "Mozilla/5.0...",
      "created_at": "2025-06-01T14:22:00+00:00"
    }
  ],
  "total": 1024,
  "page": 1,
  "per_page": 50,
  "filter_options": {
    "sorts": ["-created_at", "created_at", "event_type", "..."],
    "search_fields": [{ "key": "user_id", "label": "User ID" }],
    "fields": [
      {
        "key": "status",
        "label": "Status",
        "value_type": "enum",
        "operator": "is",
        "multiple": true,
        "options": [{ "value": "5xx", "label": "5xx Server error" }],
        "supports_custom_text": false
      }
    ]
  }
}
```

#### GET /api/v1/admin/audit-log/verify

Verify the tamper-evident audit-log hash chain over a bounded range. A broken chain returns HTTP 200 with `status: "broken"` because the integrity break is the report finding, not a transport error.

**Auth:** Admin or operator

**Query Parameters:**

| Parameter  | Type    | Default | Description |
|------------|---------|---------|-------------|
| `from_seq` | integer | `1` | First chained sequence number to verify |
| `to_seq`   | integer | -- | Optional final sequence number |
| `limit`    | integer | `10000` | Maximum rows to verify in this call, capped at 10000 |

**Response (200):**

```json
{
  "status": "ok",
  "checked_count": 10000,
  "pre_chain_count": 42,
  "head_seq": 58321,
  "head_hash": "8b7d...",
  "next_from_seq": 10001
}
```

If a break is detected, `break_info` contains the first broken sequence, its kind (`gap`, `link_mismatch`, or `hash_mismatch`), and the expected/actual values.

**Audit Event Types:**

| Event Type                     | Description                                  |
|--------------------------------|----------------------------------------------|
| `register`                     | New user registration                        |
| `login`                        | Successful login                             |
| `logout`                       | User logout                                  |
| `admin_setup`                  | Initial admin created via bootstrap endpoint |
| `admin_promoted`               | User promoted to admin via CLI               |
| `admin.user.updated`           | Admin edited a user's profile                |
| `admin.user.role_changed`      | Admin changed a user's admin role            |
| `admin.user.status_changed`    | Admin enabled/disabled a user account        |
| `admin.user.password_reset`    | Admin forced a password reset                |
| `admin.user.deleted`           | Admin deleted a user (cascade)               |
| `admin.user.email_verified`    | Admin manually verified a user's email       |
| `admin.user.sessions_revoked`  | Admin revoked all sessions for a user        |
| `service_created`              | Downstream service registered                |
| `service_updated`              | Downstream service updated                   |
| `service_deleted`              | Downstream service deactivated               |
| `connection_created`           | User connected to a service                  |
| `connection_credential_updated`| User updated their connection credential     |
| `connection_removed`           | User disconnected from a service             |
| `oidc_credentials_accessed`    | OIDC credentials retrieved                   |
| `oidc_secret_regenerated`      | OIDC client secret regenerated               |
| `redirect_uris_updated`       | OIDC redirect URIs updated                   |
| `proxy_request`                | Request forwarded through the proxy          |
| `proxy_request_denied`         | Proxy request denied (auth or config issue)  |
| `provider_created`             | Provider configuration created               |
| `provider_updated`             | Provider configuration updated               |
| `provider_deleted`             | Provider deactivated                         |
| `provider_token_connected`     | User connected a provider token              |
| `provider_token_disconnected`  | User disconnected a provider token           |
| `provider_token_refreshed`     | Provider token manually refreshed            |
| `provider_oauth_initiated`     | User started OAuth flow with a provider      |
| `provider_oauth_callback_failed` | Provider OAuth callback failed             |
| `service_requirement_added`    | Provider requirement added to a service      |
| `service_requirement_removed`  | Provider requirement removed from a service  |

**Example:**

```bash
# Query all audit entries
curl "http://localhost:3001/api/v1/admin/audit-log?page=1&per_page=25" \
  -H "Authorization: Bearer <admin_access_token>"

# Filter by acting user
curl "http://localhost:3001/api/v1/admin/audit-log?user_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### POST /api/v1/admin/oauth-clients

Create a new OAuth client. Returns the client secret only at creation time -- it cannot be retrieved again.

**Auth:** Admin

**Request Body:**

| Field           | Type     | Required | Description                                               |
|-----------------|----------|----------|-----------------------------------------------------------|
| `name`              | string   | Yes      | Client display name                                       |
| `redirect_uris`     | string[] | Yes     | At least one redirect URI                                 |
| `client_type`       | string   | No       | `"confidential"` (default) or `"public"`                  |
| `delegation_scopes` | string   | No       | Space-separated scopes for token exchange (empty = disabled). Values: `llm:proxy`, `proxy:*`, `proxy:{service_id}`, `llm:status` |

```json
{
  "name": "My Web App",
  "redirect_uris": ["https://app.example.com/callback"],
  "client_type": "confidential",
  "delegation_scopes": "llm:proxy"
}
```

**Response (200):**

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "client_name": "My Web App",
  "client_type": "confidential",
  "redirect_uris": ["https://app.example.com/callback"],
  "allowed_scopes": "openid profile email",
  "is_active": true,
  "client_secret": "nyx_secret_abc123...",
  "created_at": "2025-06-01T10:00:00+00:00"
}
```

**Errors:**
- `1002 forbidden` -- User is not an admin
- `1008 validation_error` -- Empty name, no redirect URIs, or invalid client_type

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/admin/oauth-clients \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Web App",
    "redirect_uris": ["https://app.example.com/callback"],
    "client_type": "confidential"
  }'
```

---

#### GET /api/v1/admin/oauth-clients

List registered OAuth clients. Client secrets are never included in either response mode.

For backward compatibility, a request with none of the recognized table query parameters returns the complete unfiltered collection in the original `created_at` descending order using the legacy response shape `{ "clients": [...] }`. Unknown query parameters do not opt into table mode. Supplying any recognized table parameter, including `page=1`, opts into the bounded paginated response with filtering, sorting, and `filter_options` metadata described below.

`filter_options` is independent of the rows on the current page. Its additive `fields` array describes the field identifier, display label, value type, fixed operator, multi-select support, and labeled choices for each filter-builder field; the legacy domain arrays remain available for existing clients. The `created_at` field supports either exact multi-date selection through `created_dates` or a range through `created_from` and `created_to`.

**Auth:** Admin or operator

**Query Parameters:**

| Parameter      | Type    | Default       | Description |
|----------------|---------|---------------|-------------|
| `page`         | integer | `1`           | One-based page number |
| `per_page`     | integer | `25`          | Rows per page, clamped to `1..=100` |
| `search`       | string  | --            | Literal case-insensitive search over client name, client ID, client type, creator, and allowed scopes; maximum 256 characters |
| `search_filters` | JSON string | --         | URL-encoded field-scoped search groups; see the search semantics and limits below |
| `custom_filters` | JSON string | --        | URL-encoded per-filter free text, matched as a `contains` and OR'd with that filter's selected options; see the custom-text semantics below |
| `client_type`  | string  | --            | One or more of `public`, `confidential`, or `other` |
| `creator_type` | string  | --            | One or more of `dynamic_registration`, `system`, `owned`, or `ownerless` |
| `broker`       | string  | --            | One or more of `enabled`, `disabled`, `flag`, or `scope`; evaluated against the current broker rollout policy |
| `is_active`    | string  | --            | `true`, `false`, or both |
| `scope`        | string  | --            | One or more exact allowed-scope tokens from `filter_options.allowed_scopes` |
| `created_dates` | string | --             | One or more exact UTC creation dates as comma-separated `YYYY-MM-DD` values; maximum 32 |
| `created_from` | date    | --            | Earliest creation date to include, as a UTC calendar date in `YYYY-MM-DD` format |
| `created_to`   | date    | --            | Latest creation date to include, as a UTC calendar date in `YYYY-MM-DD` format |
| `sort`         | string  | `-created_at` | Allowlisted field; prefix `-` for descending. Fields: `client_name`, `client_type`, `created_by`, `broker`, `is_active`, `allowed_scopes`, `created_at` |

The five structured filter parameters accept comma-separated values, for example `client_type=public,confidential&scope=openid,email`. Values within one field are combined with OR; separate fields are combined with AND. Tokens are trimmed, duplicate values are canonicalized, and empty or unknown values return `400 validation_error`. Scalar requests such as `is_active=true` retain their existing behavior. `is_active=true,false` is equivalent to omitting the status filter. A multi-value `scope` filter matches a client containing any selected exact whitespace-delimited scope token; it does not require every selected scope and does not match lookalike prefixes or suffixes.

`search_filters` is a URL-encoded JSON array of field groups. Supported fields are `client`, `client_type`, `created_by`, and `allowed_scopes`; the response advertises the same set in `filter_options.search_fields`. Each group has the shape `{"field":"client","values":["console","portal"]}`. The `client` field corresponds to the visible Client column and matches both client name and client ID. Values within the same field are literal case-insensitive matches combined with OR. Different field groups are combined with AND. A simultaneously supplied legacy `search` is another AND group, while retaining its OR-across-all-fields behavior.

The array permits at most five unique field groups, eight values per group, and 32 values in total. Every value is trimmed, must be non-empty, and may contain at most 256 Unicode characters. Unknown or duplicate fields, empty arrays or values, extra object properties, malformed JSON, and exceeded limits return `400 validation_error`. Search values are treated literally; regular-expression metacharacters have no special meaning.

`custom_filters` is a URL-encoded JSON object mapping a filter key to its free-text values, for example `{"client_type":["machine"],"creator_type":["d0d7b72a"]}`. Only filters backed by a single string column accept custom text: `client_type` (matched against `client_type`), `creator_type` (matched against `created_by`), and `scope` (matched against `allowed_scopes`). `is_active` is a boolean, `broker` is derived from several fields, and `created_at` is a date, so none of them has a column a substring could match; supplying custom text for them returns `400 validation_error`. Each field in `filter_options.fields` advertises its capability as `supports_custom_text`.

Each custom value is a literal case-insensitive `contains` match; regular-expression metacharacters have no special meaning. A filter's custom values are combined with OR against that same filter's selected options, so `client_type=public&custom_filters={"client_type":["machine"]}` matches clients whose type is `public` **or** contains `machine`. This widens one filter rather than narrowing the result set, which is what distinguishes it from `search_filters` (a separate AND group). A filter carrying only custom text and no selected options still applies. The object permits at most five filters, eight values per filter, and 32 values in total; every value is trimmed, must be non-empty, and may contain at most 256 Unicode characters. Unknown filters, empty arrays or values, malformed JSON, and exceeded limits return `400 validation_error`.

`created_dates` accepts up to 32 comma-separated UTC calendar dates. Values are trimmed and deduplicated, but empty or malformed values are rejected. Each selected date matches its complete UTC day, and selected dates are combined with OR. `created_dates` cannot be combined with `created_from` or `created_to`; doing so returns `400 validation_error`.

`created_from` and `created_to` may be supplied independently or together. Both are interpreted as UTC calendar dates. The lower bound is inclusive at `00:00:00Z`; the upper bound includes the entire selected day and is implemented as an exclusive comparison against the following day's `00:00:00Z`. Invalid dates and ranges where `created_from` is after `created_to` return `400 validation_error`. The selected exact-date or range group is ANDed with search and every structured filter.

`broker` sorting uses the effective source shown in the table: ascending order is disabled (`none`), enabled by legacy scope (`scope`), then enabled by explicit flag (`flag`). Descending order reverses it. When the runtime policy requires explicit admin capability, scope-only clients sort as disabled. `allowed_scopes` sorts the stored canonical space-separated scope string. Every sort adds `created_at` and `_id` tie-breakers (or just `_id` when sorting by `created_at`) in the requested direction, so pagination order is deterministic.

**Legacy response (200, no recognized table parameters):**

```json
{
  "clients": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "client_name": "My Web App",
      "client_type": "confidential",
      "created_by": "550e8400-e29b-41d4-a716-446655440000",
      "redirect_uris": ["https://app.example.com/callback"],
      "allowed_scopes": "openid profile email",
      "delegation_scopes": "",
      "broker_capability_enabled": false,
      "broker_capability_effective": false,
      "broker_capability_source": "none",
      "revocation_webhook_url": null,
      "is_active": true,
      "client_secret": null,
      "created_at": "2025-06-01T10:00:00+00:00"
    }
  ]
}
```

**Paginated response (200, any recognized table parameter):**

```json
{
  "clients": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "client_name": "My Web App",
      "client_type": "confidential",
      "created_by": "550e8400-e29b-41d4-a716-446655440000",
      "redirect_uris": ["https://app.example.com/callback"],
      "allowed_scopes": "openid profile email",
      "delegation_scopes": "",
      "broker_capability_enabled": false,
      "broker_capability_effective": false,
      "broker_capability_source": "none",
      "revocation_webhook_url": null,
      "is_active": true,
      "client_secret": null,
      "created_at": "2025-06-01T10:00:00+00:00"
    }
  ],
  "total": 142,
  "page": 1,
  "per_page": 25,
  "filter_options": {
    "client_types": ["public", "confidential", "other"],
    "creator_types": ["dynamic_registration", "system", "owned", "ownerless"],
    "broker_filters": ["enabled", "disabled", "flag", "scope"],
    "statuses": [true, false],
    "allowed_scopes": [
      "openid",
      "profile",
      "email",
      "roles",
      "groups",
      "offline_access",
      "proxy",
      "urn:nyxid:scope:broker_binding"
    ],
    "sorts": [
      "-created_at",
      "created_at",
      "client_name",
      "-client_name",
      "client_type",
      "-client_type",
      "created_by",
      "-created_by",
      "broker",
      "-broker",
      "-is_active",
      "is_active",
      "allowed_scopes",
      "-allowed_scopes"
    ],
    "search_fields": [
      { "key": "client", "label": "Client" },
      { "key": "client_type", "label": "Client type" },
      { "key": "created_by", "label": "Created by" },
      { "key": "allowed_scopes", "label": "Allowed scopes" }
    ],
    "fields": [
      {
        "key": "is_active",
        "label": "Status",
        "value_type": "boolean",
        "operator": "is",
        "multiple": true,
        "options": [
          { "value": "true", "label": "Active" },
          { "value": "false", "label": "Inactive" }
        ]
      },
      {
        "key": "client_type",
        "label": "Client type",
        "value_type": "enum",
        "operator": "is",
        "multiple": true,
        "options": [
          { "value": "public", "label": "Public" },
          { "value": "confidential", "label": "Confidential" },
          { "value": "other", "label": "Other" }
        ]
      },
      {
        "key": "creator_type",
        "label": "Creator",
        "value_type": "enum",
        "operator": "is",
        "multiple": true,
        "options": [
          { "value": "dynamic_registration", "label": "Dynamic registration" },
          { "value": "system", "label": "System" },
          { "value": "owned", "label": "User / org" },
          { "value": "ownerless", "label": "Ownerless" }
        ]
      },
      {
        "key": "broker",
        "label": "Broker capability",
        "value_type": "enum",
        "operator": "is",
        "multiple": true,
        "options": [
          { "value": "enabled", "label": "Enabled" },
          { "value": "disabled", "label": "Disabled" },
          { "value": "flag", "label": "Enabled by admin grant" },
          { "value": "scope", "label": "Enabled by broker scope" }
        ]
      },
      {
        "key": "scope",
        "label": "Allowed scope",
        "value_type": "enum",
        "operator": "includes",
        "multiple": true,
        "options": [
          { "value": "openid", "label": "OpenID" },
          { "value": "profile", "label": "Profile" },
          { "value": "email", "label": "Email" },
          { "value": "roles", "label": "Roles" },
          { "value": "groups", "label": "Groups" },
          { "value": "offline_access", "label": "Offline access" },
          { "value": "proxy", "label": "Proxy" },
          {
            "value": "urn:nyxid:scope:broker_binding",
            "label": "Broker binding"
          }
        ]
      },
      {
        "key": "created_at",
        "label": "Created",
        "value_type": "date",
        "operator": "between",
        "multiple": true,
        "options": []
      }
    ]
  }
}
```

**Example:**

```bash
curl "http://localhost:3001/api/v1/admin/oauth-clients?page=1&per_page=25&client_type=public&sort=-created_at" \
  -H "Authorization: Bearer <admin_access_token>"
```

Multi-select filters use one comma-separated query value per field:

```bash
curl "http://localhost:3001/api/v1/admin/oauth-clients?page=1&per_page=25&client_type=public,confidential&scope=openid,email&is_active=true&sort=client_name" \
  -H "Authorization: Bearer <admin_access_token>"
```

Date bounds select complete UTC days and can be combined with search and other filters:

```bash
curl "http://localhost:3001/api/v1/admin/oauth-clients?search=openid&created_from=2026-07-01&created_to=2026-07-10&sort=-created_at" \
  -H "Authorization: Bearer <admin_access_token>"
```

Exact dates use OR within the Created field and cannot be combined with range bounds:

```bash
curl "http://localhost:3001/api/v1/admin/oauth-clients?created_dates=2026-07-01,2026-07-10&sort=-created_at" \
  -H "Authorization: Bearer <admin_access_token>"
```

Field-scoped search values in one field use OR, while separate fields use AND:

```bash
curl --get "http://localhost:3001/api/v1/admin/oauth-clients" \
  --data-urlencode 'search_filters=[{"field":"client","values":["console","portal"]},{"field":"client_type","values":["public"]}]' \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### PATCH /api/v1/admin/oauth-clients/{client_id}

Update an OAuth client by `_id` as a platform admin, including ownerless Dynamic Client Registration rows (`created_by = "dynamic_registration"`). Client secrets are never returned. Changing `redirect_uris`, `allowed_scopes`, `broker_capability_enabled`, or deactivating the client clears unused pending authorization codes for that client.

**Auth:** Admin

**Path Parameters:**

| Parameter   | Type | Description        |
|-------------|------|--------------------|
| `client_id` | UUID | The OAuth client ID |

**Request Body:** all fields are optional.

| Field                       | Type     | Description                                                  |
|-----------------------------|----------|--------------------------------------------------------------|
| `broker_capability_enabled` | boolean  | Grants or removes admin-provisioned OAuth broker capability  |
| `is_active`                 | boolean  | Activates or deactivates the client                          |
| `redirect_uris`             | string[] | Replacement redirect URI list                                |
| `allowed_scopes`            | string[] | Replacement allowed scope list                               |
| `client_name`               | string   | Replacement display name                                     |

```json
{
  "broker_capability_enabled": true
}
```

**Response (200):** updated OAuth client metadata. `client_secret` is always `null`.

**Errors:**
- `1002 forbidden` -- User is not an admin
- `1003 not_found` -- Client does not exist
- `1008 validation_error` -- Invalid redirect URI, scope, or client name

---

#### DELETE /api/v1/admin/oauth-clients/{client_id}

Deactivate an OAuth client. The client can no longer be used for authorization after this operation.

**Auth:** Admin

**Path Parameters:**

| Parameter   | Type | Description        |
|-------------|------|--------------------|
| `client_id` | UUID | The OAuth client ID |

**Response (200):**

```json
{
  "message": "OAuth client deactivated"
}
```

**Errors:**
- `1002 forbidden` -- User is not an admin
- `1003 not_found` -- Client does not exist

**Example:**

```bash
curl -X DELETE http://localhost:3001/api/v1/admin/oauth-clients/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### GET /api/v1/admin/settings/broker

Read the effective OAuth broker rollout policy. Each field reports the env default, optional DB override, effective value, and source. DB overrides win over env defaults; absent overrides fall back to env.

**Auth:** Admin

**Response (200):**

```json
{
  "broker_require_sender_constraint": {
    "effective": true,
    "env_default": false,
    "override": true,
    "source": "override"
  },
  "broker_require_admin_capability": {
    "effective": false,
    "env_default": false,
    "override": null,
    "source": "env_default"
  }
}
```

---

#### PATCH /api/v1/admin/settings/broker

Set or clear runtime OAuth broker rollout overrides. Use `true`/`false` to set a DB override; use `null` to clear an override and return to the env default. Changes update the in-memory policy cache without a restart.

**Auth:** Admin

```json
{
  "broker_require_sender_constraint": true,
  "broker_require_admin_capability": null
}
```

**Response (200):** same shape as `GET /api/v1/admin/settings/broker`.

**Errors:**
- `1002 forbidden` -- User is not an admin
- `1008 validation_error` -- Request body is malformed

---

### Admin Roles

All admin role endpoints require the authenticated user to have `is_admin = true`.

#### GET /api/v1/admin/roles

List all roles. Optionally filter by OAuth client scope.

**Auth:** Admin

**Query Parameters:**

| Parameter   | Type   | Default | Description                                 |
|-------------|--------|---------|---------------------------------------------|
| `client_id` | string | --      | Filter roles scoped to a specific client    |

**Response (200):**

```json
{
  "roles": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Admin",
      "slug": "admin",
      "description": "Full system administrator",
      "permissions": ["users:read", "users:write", "admin:*"],
      "is_default": false,
      "is_system": true,
      "client_id": null,
      "created_at": "2025-06-01T10:00:00+00:00",
      "updated_at": "2025-06-01T10:00:00+00:00"
    }
  ]
}
```

**Example:**

```bash
curl http://localhost:3001/api/v1/admin/roles \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### POST /api/v1/admin/roles

Create a new role.

**Auth:** Admin

**Request Body:**

| Field         | Type     | Required | Description                                       |
|---------------|----------|----------|---------------------------------------------------|
| `name`        | string   | Yes      | Human-readable name                               |
| `slug`        | string   | Yes      | URL-safe identifier (must be unique)              |
| `description` | string   | No       | Role description                                  |
| `permissions` | string[] | Yes      | Permission tags (e.g., `["users:read"]`)          |
| `is_default`  | boolean  | No       | Auto-assign to new users (default: false)         |
| `client_id`   | string   | No       | Scope to a specific OAuth client                  |

**Response (200):** Returns the created role object (same shape as list response items).

**Errors:**
- `1004 conflict` -- Slug already exists
- `1008 validation_error` -- Name or slug is empty

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/admin/roles \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Editor",
    "slug": "editor",
    "description": "Can edit content",
    "permissions": ["content:read", "content:write"]
  }'
```

---

#### GET /api/v1/admin/roles/{role_id}

Get a single role by ID.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type   | Description   |
|-----------|--------|---------------|
| `role_id` | string | The role ID   |

**Response (200):** Returns the role object.

**Errors:**
- `1003 not_found` -- Role does not exist

**Example:**

```bash
curl http://localhost:3001/api/v1/admin/roles/role-uuid-here \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### PUT /api/v1/admin/roles/{role_id}

Update a role. System roles (`admin`, `user`) cannot be renamed or have their slug changed.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type   | Description   |
|-----------|--------|---------------|
| `role_id` | string | The role ID   |

**Request Body (all fields optional):**

| Field         | Type     | Description                            |
|---------------|----------|----------------------------------------|
| `name`        | string   | New name                               |
| `slug`        | string   | New slug                               |
| `description` | string   | New description                        |
| `permissions` | string[] | New permissions list (replaces existing)|
| `is_default`  | boolean  | New default flag                       |

**Response (200):** Returns the updated role object.

**Errors:**
- `1002 forbidden` -- Cannot modify system role name/slug
- `1003 not_found` -- Role does not exist

**Example:**

```bash
curl -X PUT http://localhost:3001/api/v1/admin/roles/role-uuid-here \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["content:read", "content:write", "content:delete"]
  }'
```

---

#### DELETE /api/v1/admin/roles/{role_id}

Delete a role. System roles cannot be deleted.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type   | Description   |
|-----------|--------|---------------|
| `role_id` | string | The role ID   |

**Response (200):**

```json
{
  "message": "Role deleted"
}
```

**Errors:**
- `1002 forbidden` -- Cannot delete system role
- `1003 not_found` -- Role does not exist

**Example:**

```bash
curl -X DELETE http://localhost:3001/api/v1/admin/roles/role-uuid-here \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### GET /api/v1/admin/users/{user_id}/roles

Get a user's direct roles, inherited roles (via group membership), and effective permissions.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type   | Description   |
|-----------|--------|---------------|
| `user_id` | string | The user ID   |

**Response (200):**

```json
{
  "direct_roles": [
    {
      "id": "...",
      "name": "Editor",
      "slug": "editor",
      "permissions": ["content:read", "content:write"],
      "is_default": false,
      "is_system": false,
      "client_id": null,
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "inherited_roles": [
    {
      "id": "...",
      "name": "Viewer",
      "slug": "viewer",
      "permissions": ["content:read"],
      "is_default": true,
      "is_system": false,
      "client_id": null,
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "effective_permissions": ["content:read", "content:write"]
}
```

**Example:**

```bash
curl http://localhost:3001/api/v1/admin/users/user-uuid-here/roles \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### POST /api/v1/admin/users/{user_id}/roles/{role_id}

Assign a role directly to a user.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type   | Description   |
|-----------|--------|---------------|
| `user_id` | string | The user ID   |
| `role_id` | string | The role ID   |

**Response (200):**

```json
{
  "message": "Role assigned"
}
```

**Errors:**
- `1003 not_found` -- User or role does not exist
- `1004 conflict` -- Role already assigned

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/admin/users/user-uuid-here/roles/role-uuid-here \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### DELETE /api/v1/admin/users/{user_id}/roles/{role_id}

Revoke a directly-assigned role from a user.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type   | Description   |
|-----------|--------|---------------|
| `user_id` | string | The user ID   |
| `role_id` | string | The role ID   |

**Response (200):**

```json
{
  "message": "Role revoked"
}
```

**Errors:**
- `1003 not_found` -- User does not have this role

**Example:**

```bash
curl -X DELETE http://localhost:3001/api/v1/admin/users/user-uuid-here/roles/role-uuid-here \
  -H "Authorization: Bearer <admin_access_token>"
```

---

### Admin Groups

All admin group endpoints require the authenticated user to have `is_admin = true`.

#### GET /api/v1/admin/groups

List all groups with their associated roles and member counts.

**Auth:** Admin

**Response (200):**

```json
{
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Engineering",
      "slug": "engineering",
      "description": "Engineering team",
      "roles": [
        {
          "id": "...",
          "name": "Developer",
          "slug": "developer",
          "permissions": ["code:read", "code:write"],
          "is_default": false,
          "is_system": false,
          "client_id": null,
          "created_at": "...",
          "updated_at": "..."
        }
      ],
      "parent_group_id": null,
      "member_count": 12,
      "created_at": "2025-06-01T10:00:00+00:00",
      "updated_at": "2025-06-01T10:00:00+00:00"
    }
  ]
}
```

**Example:**

```bash
curl http://localhost:3001/api/v1/admin/groups \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### POST /api/v1/admin/groups

Create a new group.

**Auth:** Admin

**Request Body:**

| Field             | Type     | Required | Description                                  |
|-------------------|----------|----------|----------------------------------------------|
| `name`            | string   | Yes      | Human-readable name                          |
| `slug`            | string   | Yes      | URL-safe identifier (must be unique)         |
| `description`     | string   | No       | Group description                            |
| `role_ids`        | string[] | No       | Role IDs to attach (members inherit these)   |
| `parent_group_id` | string   | No       | Parent group ID for hierarchy                |

**Response (200):** Returns the created group object (same shape as list response items).

**Errors:**
- `1004 conflict` -- Slug already exists
- `1008 validation_error` -- Name or slug is empty

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/admin/groups \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering",
    "slug": "engineering",
    "description": "Engineering team",
    "role_ids": ["role-uuid-here"]
  }'
```

---

#### GET /api/v1/admin/groups/{group_id}

Get a single group by ID, including its roles and member count.

**Auth:** Admin

**Path Parameters:**

| Parameter  | Type   | Description    |
|------------|--------|----------------|
| `group_id` | string | The group ID   |

**Response (200):** Returns the group object.

**Errors:**
- `1003 not_found` -- Group does not exist

**Example:**

```bash
curl http://localhost:3001/api/v1/admin/groups/group-uuid-here \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### PUT /api/v1/admin/groups/{group_id}

Update a group.

**Auth:** Admin

**Path Parameters:**

| Parameter  | Type   | Description    |
|------------|--------|----------------|
| `group_id` | string | The group ID   |

**Request Body (all fields optional):**

| Field             | Type     | Description                                  |
|-------------------|----------|----------------------------------------------|
| `name`            | string   | New name                                     |
| `slug`            | string   | New slug                                     |
| `description`     | string   | New description                              |
| `role_ids`        | string[] | New role IDs (replaces existing)             |
| `parent_group_id` | string   | New parent group ID (empty string to unset)  |

**Response (200):** Returns the updated group object.

**Errors:**
- `1003 not_found` -- Group does not exist

**Example:**

```bash
curl -X PUT http://localhost:3001/api/v1/admin/groups/group-uuid-here \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role_ids": ["role-uuid-1", "role-uuid-2"]
  }'
```

---

#### DELETE /api/v1/admin/groups/{group_id}

Delete a group. Members are not deleted, but lose the group's inherited roles.

**Auth:** Admin

**Path Parameters:**

| Parameter  | Type   | Description    |
|------------|--------|----------------|
| `group_id` | string | The group ID   |

**Response (200):**

```json
{
  "message": "Group deleted"
}
```

**Errors:**
- `1003 not_found` -- Group does not exist

**Example:**

```bash
curl -X DELETE http://localhost:3001/api/v1/admin/groups/group-uuid-here \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### GET /api/v1/admin/groups/{group_id}/members

List all members of a group.

**Auth:** Admin

**Path Parameters:**

| Parameter  | Type   | Description    |
|------------|--------|----------------|
| `group_id` | string | The group ID   |

**Response (200):**

```json
{
  "members": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "display_name": "Jane Doe"
    }
  ],
  "total": 1
}
```

**Example:**

```bash
curl http://localhost:3001/api/v1/admin/groups/group-uuid-here/members \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### POST /api/v1/admin/groups/{group_id}/members/{user_id}

Add a user to a group. The user inherits the group's roles.

**Auth:** Admin

**Path Parameters:**

| Parameter  | Type   | Description    |
|------------|--------|----------------|
| `group_id` | string | The group ID   |
| `user_id`  | string | The user ID    |

**Response (200):**

```json
{
  "message": "Member added"
}
```

**Errors:**
- `1003 not_found` -- Group or user does not exist
- `1004 conflict` -- User is already a member

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/admin/groups/group-uuid-here/members/user-uuid-here \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### DELETE /api/v1/admin/groups/{group_id}/members/{user_id}

Remove a user from a group. The user loses the group's inherited roles.

**Auth:** Admin

**Path Parameters:**

| Parameter  | Type   | Description    |
|------------|--------|----------------|
| `group_id` | string | The group ID   |
| `user_id`  | string | The user ID    |

**Response (200):**

```json
{
  "message": "Member removed"
}
```

**Errors:**
- `1003 not_found` -- User is not a member of this group

**Example:**

```bash
curl -X DELETE http://localhost:3001/api/v1/admin/groups/group-uuid-here/members/user-uuid-here \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### GET /api/v1/admin/users/{user_id}/groups

Get all groups a user belongs to.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type   | Description   |
|-----------|--------|---------------|
| `user_id` | string | The user ID   |

**Response (200):**

```json
{
  "groups": [
    {
      "id": "...",
      "name": "Engineering",
      "slug": "engineering",
      "description": "Engineering team",
      "roles": [...],
      "parent_group_id": null,
      "member_count": 12,
      "created_at": "...",
      "updated_at": "..."
    }
  ]
}
```

**Example:**

```bash
curl http://localhost:3001/api/v1/admin/users/user-uuid-here/groups \
  -H "Authorization: Bearer <admin_access_token>"
```

---

### Admin Service Accounts

Service accounts are non-human (machine-to-machine) identities that authenticate via OAuth2 Client Credentials Grant. All admin endpoints require `is_admin = true`.

#### POST /api/v1/admin/service-accounts

Create a new service account. The `client_secret` is returned once in the response and cannot be retrieved later.

**Auth:** Admin

**Request Body:**

| Field                 | Type     | Required | Description                                  |
|-----------------------|----------|----------|----------------------------------------------|
| `name`                | string   | Yes      | Human-readable name (1-100 chars)            |
| `description`         | string   | No       | Description (max 500 chars)                  |
| `allowed_scopes`      | string   | Yes      | Space-separated allowed scopes               |
| `role_ids`            | string[] | No       | Role IDs to assign                           |
| `rate_limit_override` | number   | No       | Per-account rate limit (requests/second)     |

```json
{
  "name": "CI/CD Pipeline",
  "description": "Automated deployment service",
  "allowed_scopes": "proxy:* llm:proxy",
  "role_ids": ["role-uuid-here"],
  "rate_limit_override": 50
}
```

**Response (200):**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "CI/CD Pipeline",
  "client_id": "sa_a1b2c3d4e5f6a1b2c3d4e5f6",
  "client_secret": "sas_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "allowed_scopes": "proxy:* llm:proxy",
  "role_ids": ["role-uuid-here"],
  "is_active": true,
  "created_at": "2025-06-01T10:00:00+00:00",
  "message": "Service account created. Save the client_secret now -- it cannot be retrieved later."
}
```

**Errors:**
- `1008 validation_error` -- Name is empty or too long

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/admin/service-accounts \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "allowed_scopes": "proxy:* llm:proxy"
  }'
```

---

#### GET /api/v1/admin/service-accounts

List all service accounts with pagination and optional search.

**Auth:** Admin

**Query Parameters:**

| Parameter  | Type   | Default | Description                       |
|------------|--------|---------|-----------------------------------|
| `page`     | number | `1`     | Page number                       |
| `per_page` | number | `20`    | Items per page                    |
| `search`   | string | --      | Filter by name (case-insensitive) |

**Response (200):**

```json
{
  "service_accounts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "CI/CD Pipeline",
      "description": "Automated deployment service",
      "client_id": "sa_a1b2c3d4e5f6a1b2c3d4e5f6",
      "secret_prefix": "sas_xxxx",
      "allowed_scopes": "proxy:* llm:proxy",
      "role_ids": ["role-uuid-here"],
      "is_active": true,
      "rate_limit_override": 50,
      "created_by": "admin-uuid-here",
      "created_at": "2025-06-01T10:00:00+00:00",
      "updated_at": "2025-06-01T10:00:00+00:00",
      "last_authenticated_at": "2025-06-15T08:30:00+00:00"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}
```

**Example:**

```bash
curl "http://localhost:3001/api/v1/admin/service-accounts?page=1&per_page=10&search=pipeline" \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### GET /api/v1/admin/service-accounts/{sa_id}

Get a single service account by ID.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type   | Description            |
|-----------|--------|------------------------|
| `sa_id`   | string | Service account UUID   |

**Response (200):** Same shape as a single item in the list response.

**Errors:**
- `5000 service_account_not_found` -- Service account does not exist

**Example:**

```bash
curl http://localhost:3001/api/v1/admin/service-accounts/sa-uuid-here \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### PUT /api/v1/admin/service-accounts/{sa_id}

Update a service account's mutable fields. All fields are optional; only provided fields are updated.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type   | Description            |
|-----------|--------|------------------------|
| `sa_id`   | string | Service account UUID   |

**Request Body:**

| Field                 | Type      | Required | Description                                |
|-----------------------|-----------|----------|--------------------------------------------|
| `name`                | string    | No       | New name (1-100 chars)                     |
| `description`         | string    | No       | New description (max 500 chars)            |
| `allowed_scopes`      | string    | No       | New allowed scopes                         |
| `role_ids`            | string[]  | No       | New role assignments                       |
| `rate_limit_override` | number?   | No       | New rate limit (null to remove override)   |
| `is_active`           | boolean   | No       | Enable or disable the account              |

**Response (200):** Returns the updated service account (same shape as list item).

**Errors:**
- `5000 service_account_not_found` -- Service account does not exist

**Example:**

```bash
curl -X PUT http://localhost:3001/api/v1/admin/service-accounts/sa-uuid-here \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name", "is_active": false}'
```

---

#### DELETE /api/v1/admin/service-accounts/{sa_id}

Soft-delete (deactivate) a service account and revoke all its tokens.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type   | Description            |
|-----------|--------|------------------------|
| `sa_id`   | string | Service account UUID   |

**Response (200):**

```json
{
  "message": "Service account deleted"
}
```

**Errors:**
- `5000 service_account_not_found` -- Service account does not exist

**Example:**

```bash
curl -X DELETE http://localhost:3001/api/v1/admin/service-accounts/sa-uuid-here \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### POST /api/v1/admin/service-accounts/{sa_id}/rotate-secret

Generate a new client secret and revoke all existing tokens. The new secret is returned once.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type   | Description            |
|-----------|--------|------------------------|
| `sa_id`   | string | Service account UUID   |

**Response (200):**

```json
{
  "client_id": "sa_a1b2c3d4e5f6a1b2c3d4e5f6",
  "client_secret": "sas_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
  "secret_prefix": "sas_yyyy",
  "message": "Secret rotated. All existing tokens have been revoked. Save the new secret now."
}
```

**Errors:**
- `5000 service_account_not_found` -- Service account does not exist

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/admin/service-accounts/sa-uuid-here/rotate-secret \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### POST /api/v1/admin/service-accounts/{sa_id}/revoke-tokens

Revoke all active tokens for a service account without rotating the secret.

**Auth:** Admin

**Path Parameters:**

| Parameter | Type   | Description            |
|-----------|--------|------------------------|
| `sa_id`   | string | Service account UUID   |

**Response (200):**

```json
{
  "revoked_count": 5,
  "message": "All tokens revoked"
}
```

**Errors:**
- `5000 service_account_not_found` -- Service account does not exist

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/admin/service-accounts/sa-uuid-here/revoke-tokens \
  -H "Authorization: Bearer <admin_access_token>"
```

---

#### Service Account Authentication (Client Credentials)

Service accounts authenticate at the existing `POST /oauth/token` endpoint using the `client_credentials` grant type.

**Request:**

```
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=sa_a1b2c3d4e5f6...&client_secret=sas_xxxxxxxx...&scope=proxy:* llm:proxy
```

Or with HTTP Basic Authentication:

```
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=client_credentials&scope=proxy:* llm:proxy
```

**Response (200):**

```json
{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "proxy:* llm:proxy"
}
```

The `scope` parameter is optional. If omitted, all of the service account's `allowed_scopes` are granted. If provided, the requested scopes must be a subset of `allowed_scopes`.

No refresh token is issued. When the access token expires, the service account must re-authenticate with client credentials.

**Errors:**
- `1001 unauthorized` -- Invalid client_id or client_secret
- `5001 service_account_inactive` -- Service account is deactivated
- `3002 invalid_scope` -- Requested scope not allowed

**Example:**

```bash
curl -X POST http://localhost:3001/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=client_credentials&client_id=sa_a1b2c3d4e5f6...&client_secret=sas_xxxxxxxx...&scope=proxy:*'
```

---

## JWT Token Format

All JWTs are signed with RS256 (RSA SHA-256) using a 4096-bit key pair.

### Access Token Claims

| Claim        | Type   | Description                       |
|--------------|--------|-----------------------------------|
| Claim         | Type     | Description                                       |
|---------------|----------|---------------------------------------------------|
| `sub`         | string   | User ID (UUID)                                    |
| `iss`         | string   | Issuer (matches `JWT_ISSUER`)                     |
| `aud`         | string   | Audience (matches `BASE_URL`)                     |
| `exp`         | number   | Expiration (Unix timestamp)                       |
| `iat`         | number   | Issued at (Unix timestamp)                        |
| `jti`         | string   | Unique token ID (UUID)                            |
| `scope`       | string   | Space-separated scopes                            |
| `token_type`  | string   | `"access"`                                        |
| `roles`       | string[] | Role slugs (present when `roles` scope requested) |
| `groups`      | string[] | Group slugs (present when `groups` scope requested)|
| `permissions` | string[] | Effective permissions (present when `roles` scope requested) |
| `acr`         | string   | Authentication Context Class Reference            |
| `amr`         | string[] | Authentication Methods References                 |
| `auth_time`   | number   | Time of authentication (Unix timestamp)           |
| `sid`         | string   | Session ID                                        |

The `roles`, `groups`, and `permissions` claims are only included when the corresponding scopes (`roles`, `groups`) are requested in the OAuth authorization flow.

### Refresh Token Claims

Same structure as access tokens, but:
- `token_type` is `"refresh"`
- `scope` is empty
- `exp` uses `JWT_REFRESH_TTL_SECS` (default: 7 days)
- RBAC claims (`roles`, `groups`, `permissions`) are not included

### Service Account Token Claims

Service account access tokens include:

| Claim        | Type   | Description                                        |
|--------------|--------|----------------------------------------------------|
| `sub`        | string | Service account ID (UUID)                          |
| `iss`        | string | Issuer (matches `JWT_ISSUER`)                      |
| `aud`        | string | Audience (matches `BASE_URL`)                      |
| `exp`        | number | Expiration (Unix timestamp)                        |
| `iat`        | number | Issued at (Unix timestamp)                         |
| `jti`        | string | Unique token ID (UUID, used for revocation)        |
| `scope`      | string | Space-separated granted scopes                     |
| `token_type` | string | `"access"`                                         |
| `sa`         | boolean| Always `true` for service account tokens           |

Service account tokens do **not** include `sid`, `roles`, `groups`, `permissions`, `act`, or `delegated` claims. No refresh tokens are issued for service accounts.

---

## Notification Settings

Manage notification channels and approval preferences. All endpoints require authentication (human-only, no service accounts or delegated tokens).

### Get Notification Settings

```
GET /api/v1/notifications/settings
Authorization: Bearer <access_token>
```

**Response (200):**

```json
{
  "telegram_connected": true,
  "telegram_username": "johndoe",
  "telegram_enabled": true,
  "push_enabled": true,
  "push_device_count": 1,
  "approval_required": true,
  "approval_suspended": false,
  "approval_timeout_secs": 30,
  "grant_expiry_days": 30
}
```

The global `approval_required` preference is enforced only while at least one Telegram or push notification channel is active. `approval_suspended` is `true` when the stored preference remains on but no channel is currently available; enforcement resumes automatically when a channel becomes active again.

**curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3001/api/v1/notifications/settings
```

### Update Notification Settings

```
PUT /api/v1/notifications/settings
Authorization: Bearer <access_token>
Content-Type: application/json
```

**Request:**

```json
{
  "telegram_enabled": true,
  "approval_required": true,
  "approval_timeout_secs": 60,
  "grant_expiry_days": 14
}
```

All fields are optional. Only provided fields are updated.

**Validation:**
- `approval_timeout_secs`: 10..=300
- `grant_expiry_days`: 1..=365
- `telegram_enabled: true` requires a linked Telegram account
- `approval_required: true` (turning it on from off) requires an active Telegram or push channel; an already-enabled preference may keep its value while channels are disabled (protection is suspended)

**Response (200):**

```json
{
  "telegram_connected": true,
  "telegram_username": "johndoe",
  "telegram_enabled": true,
  "push_enabled": true,
  "push_device_count": 1,
  "approval_required": true,
  "approval_suspended": false,
  "approval_timeout_secs": 60,
  "grant_expiry_days": 14
}
```

**curl:**

```bash
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"approval_required": true, "approval_timeout_secs": 60}' \
  http://localhost:3001/api/v1/notifications/settings
```

### Generate Telegram Link Code

```
POST /api/v1/notifications/telegram/link
Authorization: Bearer <access_token>
```

Generates a one-time code that the user sends to the NyxID Telegram bot via `/start <code>`.

**Response (200):**

```json
{
  "link_code": "NYXID-A1B2C3D4",
  "bot_username": "NyxIDBot",
  "expires_in_secs": 300,
  "instructions": "Send /start NYXID-A1B2C3D4 to @NyxIDBot on Telegram"
}
```

**curl:**

```bash
curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://localhost:3001/api/v1/notifications/telegram/link
```

### Disconnect Telegram

```
DELETE /api/v1/notifications/telegram
Authorization: Bearer <access_token>
```

Clears the linked Telegram account and disables Telegram notifications.

**Response (200):**

```json
{
  "message": "Telegram disconnected"
}
```

If approval protection remains enabled but no active channel remains, the message is `Telegram disconnected. Approval protection is suspended until a notification channel is available; it resumes automatically.`

**curl:**

```bash
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://localhost:3001/api/v1/notifications/telegram
```

---

## Device Token Management

Register, list, and remove mobile push notification device tokens (FCM and APNs). All endpoints require authentication (human-only, no service accounts or delegated tokens).

### Register Device Token

```
POST /api/v1/notifications/devices
Authorization: Bearer <access_token>
Content-Type: application/json
```

Register or refresh a device token for push notifications. If a device with the same `token` already exists, its metadata is updated (token refresh). The first registered device automatically enables push notifications. Registration never changes the stored `approval_required` preference; if protection was suspended, it resumes from that existing preference when the push channel becomes active.

**Request Body:**

| Field         | Type   | Required | Description                                           |
|---------------|--------|----------|-------------------------------------------------------|
| `platform`    | string | Yes      | `"fcm"` or `"apns"`                                  |
| `token`       | string | Yes      | Device registration token (max 4096 chars)            |
| `device_name` | string | No       | Human-readable name (max 100 chars, e.g. "iPhone 15") |
| `app_id`      | string | APNs: Yes, FCM: No | App bundle ID (used as APNs topic, max 256 chars) |

```json
{
  "platform": "fcm",
  "token": "dGVzdC1kZXZpY2UtdG9rZW4...",
  "device_name": "iPhone 15 Pro",
  "app_id": "dev.nyxid.app"
}
```

**Validation:**
- `platform`: Must be `"fcm"` or `"apns"`
- `token`: Non-empty, max 4096 characters. APNs tokens must be hex-only; FCM tokens allow alphanumeric, `:`, `-`, `_`
- `app_id`: Required when `platform` is `"apns"`
- Maximum 10 devices per user

**Response (200):**

```json
{
  "device_id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "fcm",
  "device_name": "iPhone 15 Pro",
  "registered_at": "2026-03-03T12:00:00+00:00"
}
```

**Errors:**
- `1000 bad_request` -- Maximum 10 devices exceeded
- `1008 validation_error` -- Invalid platform, empty token, token too long, missing app_id for APNs, invalid token characters

**curl:**

```bash
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"platform": "fcm", "token": "device-token-here", "device_name": "Pixel 8"}' \
  http://localhost:3001/api/v1/notifications/devices
```

### List Registered Devices

```
GET /api/v1/notifications/devices
Authorization: Bearer <access_token>
```

Returns all registered push notification devices for the current user. Device tokens are NOT returned (they are secret credentials).

**Response (200):**

```json
{
  "devices": [
    {
      "device_id": "550e8400-e29b-41d4-a716-446655440000",
      "platform": "fcm",
      "device_name": "iPhone 15 Pro",
      "registered_at": "2026-03-03T12:00:00+00:00",
      "last_used_at": "2026-03-03T14:30:00+00:00"
    },
    {
      "device_id": "660e8400-e29b-41d4-a716-446655440001",
      "platform": "apns",
      "device_name": "iPad Air",
      "registered_at": "2026-03-01T08:00:00+00:00",
      "last_used_at": null
    }
  ],
  "push_enabled": true
}
```

**curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3001/api/v1/notifications/devices
```

### Remove Device

```
DELETE /api/v1/notifications/devices/{device_id}
Authorization: Bearer <access_token>
```

Remove a registered push notification device. If no devices remain after removal, push notifications are automatically disabled.

**Response (200):**

```json
{
  "message": "Device removed"
}
```

If approval protection remains enabled but no active channel remains, the message is `Device removed. Approval protection is suspended until a notification channel is available; it resumes automatically.`

**Errors:**
- `1003 not_found` -- Device not found

**curl:**

```bash
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://localhost:3001/api/v1/notifications/devices/550e8400-e29b-41d4-a716-446655440000
```

---

## Approval Management

View approval history, manage grants, and approve/reject requests via the web UI. All endpoints require authentication. The status polling endpoint is also accessible by delegated tokens and service accounts.

**Blocking vs. polling:** The primary approval flow is blocking -- proxy and LLM gateway requests hold the HTTP connection open until approval/rejection/timeout. The status polling endpoint below is a secondary mechanism for callers that use async workflows or need to monitor approval status from a separate connection.

### List Approval Requests (History)

```
GET /api/v1/approvals/requests?status=pending&page=1&per_page=20
Authorization: Bearer <access_token>
```

**Query parameters:**

| Parameter  | Type   | Default | Description                                |
|------------|--------|---------|--------------------------------------------|
| `status`   | string |         | Filter by status: `pending`, `approved`, `rejected`, `expired` |
| `page`     | number | `1`     | Page number (1-indexed)                    |
| `per_page` | number | `20`    | Results per page (max 100)                 |

**Response (200):**

```json
{
  "requests": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "service_name": "OpenAI API",
      "service_slug": "openai",
      "requester_type": "service_account",
      "requester_label": "CI Pipeline",
      "operation_summary": "proxy:POST /v1/chat/completions",
      "status": "approved",
      "created_at": "2026-03-03T00:00:00+00:00",
      "decided_at": "2026-03-03T00:00:05+00:00",
      "decision_channel": "telegram"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 20
}
```

**curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3001/api/v1/approvals/requests?status=pending"
```

### Poll Approval Request Status

```
GET /api/v1/approvals/requests/{request_id}/status
Authorization: Bearer <access_token>
```

Status endpoint for monitoring approval requests. The primary flow is blocking (proxy/LLM connections wait for approval), but this endpoint is available for async callers that manage approval status separately. Also accessible by delegated tokens and service accounts.

The caller must authenticate and match the original approval request binding:
- resource owner (`approval_request.user_id`)
- `requester_type`
- `requester_id`

This prevents authenticated callers from polling approval requests that belong to a different caller context.

**Response (200):**

```json
{
  "status": "pending",
  "expires_at": "2026-03-03T00:00:30+00:00"
}
```

Status values: `pending`, `approved`, `rejected`, `expired`.

When status changes to `approved`, the caller can retry the original proxy request (the grant now exists).

**curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3001/api/v1/approvals/requests/550e8400-e29b-41d4-a716-446655440000/status
```

### Approve/Reject via Web UI

```
POST /api/v1/approvals/requests/{request_id}/decide
Authorization: Bearer <access_token>
Content-Type: application/json
```

**Request:**

```json
{
  "approved": true
}
```

Only the resource owner (the user who must approve) can call this endpoint.

**Response (200):**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "approved",
  "decided_at": "2026-03-03T00:00:05+00:00"
}
```

**Error (404):** Request not found or already processed (replay-safe).

**curl:**

```bash
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"approved": true}' \
  http://localhost:3001/api/v1/approvals/requests/550e8400-e29b-41d4-a716-446655440000/decide
```

### List Active Grants

```
GET /api/v1/approvals/grants?page=1&per_page=20
Authorization: Bearer <access_token>
```

Returns active (non-expired, non-revoked) approval grants for the current user.

**Response (200):**

```json
{
  "grants": [
    {
      "id": "uuid",
      "service_id": "uuid",
      "service_name": "OpenAI API",
      "requester_type": "service_account",
      "requester_id": "uuid",
      "requester_label": "CI Pipeline",
      "granted_at": "2026-03-03T00:00:00+00:00",
      "expires_at": "2026-04-02T00:00:00+00:00"
    }
  ],
  "total": 5,
  "page": 1,
  "per_page": 20
}
```

**curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3001/api/v1/approvals/grants
```

### Revoke a Grant

```
DELETE /api/v1/approvals/grants/{grant_id}
Authorization: Bearer <access_token>
```

Revokes a specific approval grant. The requester will need to re-approve on their next access attempt.

**Response (200):**

```json
{
  "message": "Grant revoked"
}
```

**curl:**

```bash
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://localhost:3001/api/v1/approvals/grants/550e8400-e29b-41d4-a716-446655440000
```

### List Per-Service Approval Configs

```
GET /api/v1/approvals/service-configs
Authorization: Bearer <access_token>
```

**Auth:** Required (human-only -- rejects delegated tokens and service account tokens).

Returns all per-service approval configurations for the current user. These override the global `approval_required` setting on a per-service basis (only the global fallback is subject to channel suspension and the auto-connected exemption).

**Response (200):**

```json
{
  "configs": [
    {
      "service_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "service_name": "OpenAI API",
      "approval_required": false,
      "created_at": "2026-03-03T00:00:00+00:00",
      "updated_at": "2026-03-03T00:00:00+00:00"
    }
  ]
}
```

**curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3001/api/v1/approvals/service-configs
```

### Set Per-Service Approval Config

```
PUT /api/v1/approvals/service-configs/{service_id}
Authorization: Bearer <access_token>
Content-Type: application/json
```

**Auth:** Required (human-only).

Creates or updates a per-service approval override. When set, this value takes precedence over the global `notification_channels.approval_required` setting for the specified service (only the global fallback is subject to channel suspension and the auto-connected exemption).

**Request:**

```json
{
  "approval_required": false
}
```

| Field               | Type    | Required | Description                              |
|---------------------|---------|----------|------------------------------------------|
| `approval_required` | boolean | Yes      | Whether approval is required for this service |

**Response (200):**

```json
{
  "service_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "service_name": "OpenAI API",
  "approval_required": false,
  "created_at": "2026-03-03T00:00:00+00:00",
  "updated_at": "2026-03-03T12:00:00+00:00"
}
```

**Error (404):** Service not found.

**curl:**

```bash
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"approval_required": false}' \
  http://localhost:3001/api/v1/approvals/service-configs/a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

### Delete Per-Service Approval Config

```
DELETE /api/v1/approvals/service-configs/{service_id}
Authorization: Bearer <access_token>
```

**Auth:** Required (human-only).

Removes the per-service approval override, reverting to the global `approval_required` setting for this service (the global fallback is subject to channel suspension and the auto-connected exemption).

**Response (200):**

```json
{
  "message": "Per-service approval config removed"
}
```

**Error (404):** Per-service approval config not found.

**curl:**

```bash
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://localhost:3001/api/v1/approvals/service-configs/a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

---

## X channel event selection

Human owners and owning-org admins can `PATCH /api/v1/channel-bots/{id}` with `{"x_events":["dm","mentions","replies"]}`. Choose any nonempty, unique subset. New and legacy X bots default to `dm`; omitting `x_events` preserves it. The field is X-only and appears on bot detail responses.

`mentions` receives explicit @mentions; `replies` receives direct replies to the connected account's posts. Public events require configured X webhook credentials and user OAuth permission `tweet.write` in addition to the DM channel scopes. A missing scope fails before saving. After validation, NyxID saves the desired selection and reconciles X subscriptions; an upstream failure can therefore return an error with the selection already saved. Refresh bot detail for current status and use `POST /api/v1/channel-bots/{id}/verify` to retry after correcting the cause.

Public messages use `post:<conversation_id>` addresses. Agents use `POST /api/v1/channel-relay/reply` with the callback's NyxID `message_id` and reply token. Replies are text-only and target that incoming post; caller metadata cannot change the target. Public callbacks omit owner access tokens. Public initiated sends and edits are unsupported. See [X channel setup and limitations](CHANNEL_BOT_RELAY.md#select-mentions-and-replies) for the CLI, routing, scope and billing details.

## Telegram New Channel Creation

Telegram New is the separate `telegram-new` channel option. The existing `telegram` registration API and token-based setup remain available. See [Telegram New](TELEGRAM_NEW.md#api-and-storage) for request/response fields, status transitions, recovery rules, and administrator setup.

Routes below are relative to `/api/v1`. Creation routes require an authenticated person; API keys, service accounts, relay tokens, and delegated access are rejected. Requests are bound to the initiating person and destination. New website requests use `auto_connect: true`: the initial authenticated action authorizes connection of one fresh bot through the private Telegram handoff, and the verified creation event queues server completion with live destination-access checks. Omitting the flag preserves the legacy exact-bot approval and browser confirmation flow.

| Method | Route | Purpose |
| --- | --- | --- |
| GET | `/channel-bots/telegram-new` | Read availability and the current creation request; optional `?request_id={uuid}` reads an actor-owned request including completed setup |
| POST | `/channel-bots/telegram-new` | Prepare a request with `{label, target_org_id?, auto_connect?}`; the website sends `auto_connect: true` |
| GET | `/channel-bots/telegram-new/requests/{id}` | Read the saved request |
| POST | `/channel-bots/telegram-new/requests/{id}/launch` | Issue a fresh Telegram launch link |
| DELETE | `/channel-bots/telegram-new/requests/{id}` | Cancel before provisioning begins |
| POST | `/channel-bots/telegram-new/claims/preview` | Human-only, non-mutating preview of `{code}`; returns `{bot_username, expires_at}` without provider calls |
| POST | `/channel-bots/telegram-new/claims/redeem` | Human-only `{code, label, target_org_id?}`; atomically save the claim destination and return HTTP 202 with the connection request; worker completes setup |
| POST | `/channel-bots/telegram-new/requests/{id}/connect` | Legacy completion: confirm `{telegram_bot_id, revision}` and connect or retry |
| POST | `/webhooks/channel/telegram-new/manager` | Receive updates authenticated by the configured manager webhook secret |

Request responses expose `auto_connect` (false for legacy requests) and nullable `connection_error` with safe automatic-retry text. Automatic connection continues while the browser is closed; clients poll the saved request rather than POSTing `/connect`.

The connect body uses a decimal string for `telegram_bot_id` and an integer for `revision`, for example `{"telegram_bot_id":"900","revision":6}`. Manager credentials use the existing admin platform-credentials routes with provider `telegram-new`. Neither manager nor child bot tokens are returned to customers.

---

## Webhooks

### Aurinko email channel

The existing channel APIs accept `platform: "aurinko"`. The platform descriptor is available through `GET /api/v1/channel-platforms`, including account-token and signing-secret fields, setup instructions, and capabilities. Registration uses `POST /api/v1/channel-bots` with `label`, `bot_token`, `app_secret`, and optional `target_org_id`. Credential rotation uses the existing PATCH endpoint; `POST /api/v1/channel-bots/{id}/verify` repairs the bound subscription without changing its mailbox.

`POST /api/v1/webhooks/channel/aurinko/{id}` verifies Aurinko's signed raw request before returning a plaintext `validationToken` challenge or processing a notification. Successful/ignored notifications return 200; verification failures return 401, malformed requests 400, and recoverable failures 503 with `Retry-After: 10`. It never returns Aurinko's unsubscribe signal, 422.

Agents reply through `POST /api/v1/channel-relay/reply` with `{"message_id":"INBOUND_UUID","reply":{"text":"Reply text"}}`, using the assigned agent key or message-bound reply token. The original email determines the single recipient; recipient overrides, channel attachments, initiated sends, and edits are unsupported. A durable send barrier prevents automatic resubmission after an uncertain provider POST.

Aurinko bot deletion returns HTTP 200 with `{"webhook_cleanup":"removed"}` or `{"webhook_cleanup":"failed"}`; existing platforms retain HTTP 204. Both outcomes deactivate the bot locally. Failed cleanup requires removal of the remaining exact callback subscription in Aurinko or a later deletion retry. See [Aurinko integration](AURINKO_INTEGRATION.md) for the complete contract and independent AI Service setup.

### Inbound Triggers

Triggers provide a provider-neutral inbound event relay. Management routes accept a normal user token or agent API key and reject delegated, relay, and service-account tokens.

#### Create and manage

```http
POST /api/v1/triggers
Authorization: Bearer <access-token-or-agent-key>
Content-Type: application/json
```

```json
{
  "label": "Repository activity",
  "user_service_id": "optional-user-service-id",
  "verification": {"mode":"token","location":"bearer"},
  "delivery": {"type":"agent","conversation_id":"device-conversation-id"},
  "target_org_id": null
}
```

`verification` supports:

- `{"mode":"token","location":"bearer"}` for `Authorization: Bearer nyx_trg_...`.
- `{"mode":"token","location":"query"}` for `?token=nyx_trg_...`.
- `{"mode":"hmac_sha256","header_name":"X-Hub-Signature-256"}` for `sha256=<hex>` over the exact raw body.

Prefer bearer or HMAC verification. Query tokens are supported only for senders that cannot set headers; URLs commonly leak into reverse-proxy logs, browser history, monitoring systems, and referrer data.

`delivery` supports:

- `{"type":"webhook","url":"https://receiver.example.com/events"}`. The create/update response includes a separate `delivery_signing_secret` once and `delivery_signing_key_id`; outbound delivery uses the timestamp-bound signature and stable-header contract above.
- `{"type":"agent","conversation_id":"..."}`. The conversation must be an active NyxID device conversation owned by the trigger owner; events enter the channel-event gateway and its conversation-bound agent routing. This target does not invoke an external application's agent runtime. Use `webhook` when events must reach external infrastructure; it is also the only target with durable cross-replica dedup and the delivery-history/replay contract described below.
- `{"type":"notification"}`. The envelope is delivered through the owner's configured notification channels.

Create returns `trigger`, the one-time inbound `secret`, and optional one-time `delivery_signing_secret` plus `delivery_signing_key_id`. Other routes are:

- `GET /api/v1/triggers` and `GET /api/v1/triggers/{id}`
- `PATCH /api/v1/triggers/{id}` for `label`, `status`, or `delivery`
- `DELETE /api/v1/triggers/{id}`
- `POST /api/v1/triggers/{id}/rotate-secret`
- `POST /api/v1/triggers/{id}/rotate-delivery-secret` for webhook targets; returns a replacement `delivery_signing_secret` and `key_id` once.
- `GET /api/v1/triggers/{id}/deliveries?page=1&per_page=20` for metadata-only delivery history, newest first (`per_page` maximum 100).
- `POST /api/v1/triggers/{id}/deliveries/{event_id}/redeliver` to replay a retained encrypted envelope.

Changing a trigger's `delivery` through `PATCH` intentionally mints a replacement delivery secret. Use `rotate-delivery-secret` when only key rotation is intended. Receivers should follow the two-key `X-NyxID-Key-Id` rotation procedure documented above.

The CLI adds `nyxid trigger deliveries <id>`, `nyxid trigger redeliver <id> <event_id>`, and `nyxid trigger rotate-delivery-secret <id>` alongside the existing management commands; use `--org` for org-owned triggers.

#### Public ingress

```http
POST /api/v1/webhooks/triggers/{trigger_id}
Authorization: Bearer nyx_trg_<opaque-secret>
X-NyxID-Event-Id: provider-event-123
Content-Type: application/json

{"action":"opened","resource":{"id":"42"}}
```

The forwarded envelope is:

```json
{
  "event_id": "provider-event-123",
  "trigger_id": "trigger-uuid",
  "source": "inbound_webhook",
  "received_at": "2026-08-06T09:30:00.123Z",
  "payload": {"action":"opened","resource":{"id":"42"}}
}
```

Event identity is taken from `X-NyxID-Event-Id`, then a top-level payload `event_id`, then the SHA-256 body hash. Unknown and disabled trigger IDs both return the same not-found-shaped response. The per-trigger rate limit is applied before the body is read or an HMAC secret is decrypted. Envelope timestamps use the same RFC 3339 UTC format as connection webhooks; the wire fixture emits exactly `2026-08-06T09:30:00.123Z`.

Delivery and dedup semantics depend on the target:

- `webhook`: an atomic `trigger_deliveries` insert provides exactly-once admission and durable dedup across replicas and restarts. NyxID then returns `{"status":"accepted","event_id":"..."}` immediately and performs up to three bounded delivery attempts in the background. A sender retry returns `duplicate` even when delivery failed; use the delivery history and replay endpoint for recovery. Final failure creates a metadata-only audit event.
- `agent` and `notification`: delivery completes before the ingress response, and the event ID enters a best-effort in-memory dedup cache only after success. Dedup is per process, bounded to the configured cache capacity and a five-minute default window, and does not coordinate replicas. Concurrent or cross-replica duplicates are possible, so senders should retry failures and consumers should remain idempotent.

Webhook-target envelopes are encrypted at rest with the configured encryption keys and removed by a database TTL index after `TRIGGER_DELIVERY_RETENTION_HOURS` (72 hours by default). Delivery list responses never contain payloads. Setting retention to `0` stores metadata for the default 72-hour bounded window but no envelope, makes `replay_available` false, and causes redelivery to return `trigger_delivery_record_not_found` (11606). Agent and notification payloads are never persisted.

Delivery history entries contain `event_id`, `status` (`pending`, `delivered`, or `failed`), `attempts`, optional `last_status_code`, `replay_available`, and timestamps. Pagination responses also contain `page`, `per_page`, and `total`.

Unsupported or unconfigured agent/notification targets return HTTP 400 with `trigger_delivery_unsupported`; synchronous delivery failures return HTTP 502 with `trigger_delivery_failed`. Trigger notifications contain bounded previews rather than the full provider payload so they fit Telegram and mobile push limits.

Default ingress limits are 10 events/second per trigger, burst 20, and 256 KiB per raw request body. Outbound trigger webhook bodies are enforced at `TRIGGER_PAYLOAD_MAX_BYTES + 4096` bytes, 266240 bytes with the default configuration. See `TRIGGER_RATE_LIMIT_PER_SECOND`, `TRIGGER_RATE_LIMIT_BURST`, `TRIGGER_PAYLOAD_MAX_BYTES`, and `TRIGGER_DELIVERY_RETENTION_HOURS`.

### Telegram Webhook

```
POST /api/v1/webhooks/telegram
X-Telegram-Bot-Api-Secret-Token: <secret>
Content-Type: application/json
```

Receives Telegram updates. This endpoint is unauthenticated (no JWT/session required) but verified via the `X-Telegram-Bot-Api-Secret-Token` header using constant-time comparison.

Handles two types of updates:

1. **Callback queries** -- User pressed Approve/Reject on an inline keyboard. The handler verifies the chat ID matches the approval request, processes the decision, and edits the Telegram message to show the result.

2. **Messages** -- User sent `/start NYXID-XXXXXX` to link their Telegram account. The handler validates the link code, updates the notification channel, and sends a confirmation message.

**Response:** Always `200 OK` (empty body) to prevent Telegram retries.

This endpoint is not intended to be called directly by clients.

---

## Rate Limiting

All endpoints are subject to rate limiting. When the limit is exceeded, the server returns:

```
HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": "rate_limited",
  "error_code": 1005,
  "message": "Rate limited"
}
```

Default limits:
- **Per-IP:** 30 requests per 1-second window
- **Global:** 10 requests/second sustained with burst capacity of 30


### Catalog Skill Curation

CatalogEditor and legacy Curation service accounts use the `/catalog-curation` runtime routes below. A platform administrator grants CatalogEditor authority by saving `catalog:skills:read` and/or `catalog:skills:write` on the service account. Matching token/live scopes then cover all existing and future catalog entries. Existing role-based editors retain exact global `nyxid:catalog:skills:read/write` permission checks until an explicit admin scope save. The remaining grant requirements in this section apply only to legacy Curation. Legacy Curation runtime requests require the verified SA token, the live unexpired embedded grant, and the exact token/live account scope; their reads reveal only grant-listed catalog services. Both modes deny human credentials, API keys, delegated tokens, and relay tokens. The separate `/admin/service-accounts/{id}/curation-grant` management routes require a human platform admin.

| Method | Path | Scope or authority |
| --- | --- | --- |
| POST / DELETE | `/api/v1/admin/service-accounts/{id}/curation-grant` | Human platform admin; sticky Curation purpose/protection |
| GET | `/api/v1/catalog-curation/services` | `catalog:skills:read` |
| GET | `/api/v1/catalog-curation/services/{id}/skills` | `catalog:skills:read` |
| GET | `/api/v1/catalog-curation/services/{id}/openapi.json` | `catalog:skills:read` |
| PUT | `/api/v1/catalog-curation/services/{id}/skills` | `catalog:skills:write` |
| GET | `/api/v1/catalog-curation/services/{id}/skills/history` | `catalog:skills:read` |
| POST | `/api/v1/catalog-curation/services/{id}/skills/restore` | `catalog:skills:write` |

PUT accepts a complete `recommended_skills` and/or `recommended_skill_refs` list, optional `clear_refs`, and required `base_revision` plus UUID `request_id`. Restore accepts `revision`, `base_revision`, and `request_id`. Both reject unknown fields. Revision and budget changes, service state, history, and actor/request receipts commit atomically. Conflicting revisions or reuse of a committed ID with changed input return 409; exhausted budget returns 429. Pure no-ops write no receipt/history/revision and spend no budget.

Human `POST/PUT /api/v1/services` use the same skill validation/history path; updates accept `skills_revision`, `skills_request_id`, optional refs, and `clear_skill_refs`. Omitted update revision means expected zero. Mixed metadata effects retain full request idempotency even when skills are unchanged.

The operation-contract route returns the authorized catalog service's bounded source OpenAPI document, preserving upstream server declarations. It does not rewrite proxy URLs or grant execution access; generated skills must use the consumer's authorized NyxID service connection. It reads a configured `openapi_spec_url` through NyxID's hardened, size-limited path, resolving known hosted overlay URLs locally. When the URL is absent or empty, it falls back to an embedded overlay registered for the service slug. The configured URL must be readable without downstream credentials; this route never injects a service-account or catalog credential. Authenticated custom documents need a separate, explicitly scoped contract-fetch capability. The route never resolves a user-managed `/keys` service, injects a credential, or returns the caller-wide `/mcp/config` catalog. The discovery response includes the catalog service `id`, `slug`, `name`, and current skill revision. Catalog and MCP responses retain name recommendations and expose optional refs/revision. Ref-only changes do not change the existing `catalog_digest`; `skills_manifest_digest` is a separate versioned digest. Instance names suppress inherited refs. See [Service account curation](SERVICE_ACCOUNTS.md#catalog-skill-curation) for exact payloads, grant limits, history pagination, recovery, runtime confinement, rollout ordering, and the boundary with Ornn package content CRU.