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)
  - [Oracle Pool Lifecycle](#oracle-pool-lifecycle-unreleased)
  - [Managed Execution Status](#managed-execution-status)
  - [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)
  - [Credit Allocations](#credit-allocations)
  - [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)
  - [NyxBot service adapters](#nyxbot-service-adapters)
  - [Webhooks](#webhooks)
- [Owner NyxBot invocations](#owner-nyxbot-invocations)
- [Assistant voice and dictation](#assistant-voice-and-dictation)

---

## 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 one of the above, subject to the route's credential-type restrictions.
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.

### Channel management and agent discovery

`GET /api/v1/channel-bots` (`nyxid channel-bot list`) and `GET /api/v1/channel-conversations` (`nyxid channel-event channel list`, filtered to device channels) are human account management lists. Use a human session cookie or account access token. Personal lists are owner-scoped; `org_id` / CLI `--org` requires org-admin access. API keys (including Agent Key logins), delegated, relay and service-account tokens cannot use these lists. Existing OAuth-client account access remains subject to the route's current policy; separate first-party-only routes also reject OAuth-client tokens.

Recovery is explicit: a human can run `nyxid login` and choose account access, or select an existing human account profile. Neither the CLI nor an agent should automatically switch identity, create credentials or widen permissions after a denial.

For existing read-only agent discovery, use `GET /api/v1/channel-relay/conversations?page=1&per_page=50` with the assigned active API key. It returns only active conversations assigned to that exact key, including device channels (`platform=device`); it grants no bot inventory or management access. There is no separate channel-event discovery endpoint. A key without assignments receives an empty list. The management lists remain closed to API keys.

---

## 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"`.

Credential-type denials add fixed, metadata-only `details`; the existing HTTP status, error key, numeric code and message remain unchanged:

```json
{
  "error": "forbidden",
  "error_code": 1002,
  "message": "Forbidden: API keys cannot access this endpoint",
  "details": {
    "reason": "credential_type_unsupported",
    "credential_type": "api_key",
    "accepted": ["user_session"],
    "hint": "Ask a human to run `nyxid login` and choose account access, or use an existing human account profile. Do not switch identity automatically."
  }
}
```

`credential_type` is one of `api_key`, `delegated`, `relay`, `service_account`, or `oauth_client`. `accepted: ["user_session"]` names the supported recovery credential (a human account cookie or account access token), not an exhaustive route ACL or a permission grant. Ownership and scope checks still apply. Guidance never includes credentials, caller identifiers, resource IDs or content.

| Status | `details.reason` | Meaning / next step |
| --- | --- | --- |
| 403 | `credential_type_unsupported` | This route excludes the supplied credential type; ask a human to choose the supported account access explicitly. |
| 403 | `insufficient_scope` | A scope gate refused access; ask the owner to review only the required scopes. Changing identity is not an automatic remedy. |
| 401 | `authentication_failed` | Authentication failed (including invalid credentials); this is not a credential-type permission denial. |
| 401 | `credential_expired` | The authenticator reported expiry; this is not a credential-type permission denial. |

Resource permission denials retain their existing errors and are not labelled `credential_type_unsupported`. Older servers may omit `details`; clients must preserve their existing fallback. Credential-type middleware intentionally performs deny-only checks before authentication: its 403 does **not** certify that a credential is valid. For example, an expired API-key-shaped token still hits that early 403 on an excluded management route; on the assigned-conversation route it reaches authentication and returns 401. This ordering is unchanged.

CLI text errors preserve the existing `Error: ...` line and append the accepted credential and manual next step. JSON errors preserve the `http_error` wrapper, original `path` (including query parameters) and complete server `body`, and only add a `guidance` object with the stable reason and safe next steps. The added guidance contains no request identifiers or credentials. For the two channel lists, guidance includes the assigned-conversation alternative. No login, refresh, identity fallback or credential creation is triggered by these 403 responses.

---

## 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|
| 2003 | `mfa_step_up_required` | 403 | Verify the current session before approving a sign-in on another device |
| 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) |
| 12800 | `managed_execution_pending` | 409       | Provider outcome requires verification; inspect the execution UUID in the message and do not retry automatically |

---

## 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. New parent keys default to restricted grants and 90 days; explicit `never_expires: true` selects a nonexpiring parent. Newly issued child credentials still default to at most 90 days, bounded by the parent expiry. Explicit child expiry cannot exceed the parent. The response reports the stored parent and child expiries separately. See [issuance rollout](API_KEY_ISSUANCE.md).

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 the user's session-fallback MCP sessions
(the only ones that authenticate without a bearer). MCP sessions of OAuth clients
such as Claude and Codex present their own bearer on every request and survive.
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 UTF-8 bytes)|

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

**Response (200):**

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

**Errors:**
- `1008 validation_error` (400) -- Password outside 8–128 UTF-8 bytes
- `1000 bad_request` (400) -- Token invalid, expired, replaced, or already used

Reset completion requires an active person account that is not being deleted.
It atomically consumes the still-current token with a server-time expiry check
and revokes completed sessions, refresh tokens, pending MFA challenges and
unfinished login approval proofs in the same transaction. Reusing the current
password is permitted.

**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/password/change

Change an existing password for an active person account, including a
social-linked account that has a stored password. Passwordless accounts cannot
use this route to create a credential.

**Auth:** Verified first-party human session cookie or first-party account access
JWT. API keys, OAuth-client tokens, delegated tokens, relay tokens, service
accounts, organization identities, and inactive accounts are rejected.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `current_password` | string | Yes | Current password, nonempty and at most 128 UTF-8 bytes; historical passwords shorter than 8 bytes remain verifiable |
| `new_password` | string | Yes | 8–128 UTF-8 bytes; no character-class requirements |

```json
{
  "current_password": "currentpassword",
  "new_password": "newpassword"
}
```

**Response (200):**

```json
{
  "message": "Password changed successfully. Existing sessions remain signed in."
}
```

A new password equal to the current password is allowed, matching reset-password
behavior. Every successful change replaces the hash with a new salted Argon2id
hash, clears any pending password-reset token and expiry, and cancels pending
MFA challenges (including legacy proofs) and unfinished login approvals in one
transaction. The credential CAS requires a live active person who is not being
deleted. Proof creation/completion serializes on the same user document. Reset
completion checks its still-current token and server-time expiry at the final
write, so an obsolete reset cannot overwrite a completed change. A successful
reset revokes all sessions and refresh authority transactionally.

Completed browser, access-token, and refresh-token sessions remain valid after a
voluntary change, including the caller's session. Use the session revocation endpoints separately
when needed. Successful changes emit a metadata-only `password_changed` audit
event with `sessions_retained: true`; passwords and hashes are never returned.

Dedicated shared limits are **20 attempts/IP/minute** and **5 attempts/account/minute**,
resolved through configured trusted proxies. Attempts include successes and
counters are not reset on success. Limits run before password verification.

**Errors:**

- `400`, `1008 validation_error`: invalid byte length, incorrect current password,
  or no stored password. An incorrect password does not return `401` or sign out
  an otherwise valid session.
- `409`, `1004 conflict`: password or active-person state changed after verification;
  retry with the current credential.
- `429`, `1005 rate_limited`: an IP or account limit was reached; the session stays valid.
- `401`: missing or invalid authentication; `403`: unsupported credential or account.

---

#### 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):** For users without MFA, redirects to the frontend root and sets the `nyx_session` cookie. For users with MFA enabled, no session is created: the callback sets the narrowly scoped, HttpOnly `nyx_mfa_challenge` cookie for five minutes and redirects to `/login?mfa=required` (with a trusted `return_to` value when an OAuth authorization is being resumed).

**Response (302 on success, mobile):** For users without MFA, redirects to the provided deep link with `status=success`, `provider`, `user_id`, `access_token`, `refresh_token`, and `expires_in` query parameters. When `auth:mobile-mfa` is enabled for the signing-in person, MFA users receive no tokens; the deep link fragment contains `status=mfa_required`, `provider`, and the short-lived `mfa_token` challenge. The app posts that token and a TOTP/recovery code to `/auth/mfa/verify`. The flag defaults off: MFA users receive the normal success tokens with a persisted mobile-rollout exemption. Resolution includes live org overrides and occurs only at sign-in; a later flag flip does not revoke existing devices. While off, a social first-factor holder can sign in through mobile without an MFA code.

**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
- Existing accounts with MFA enabled must complete MFA before a browser session is issued; mobile social MFA follows `auth:mobile-mfa` (default off). The challenge token never appears in a web URL, audit row, log, or telemetry event.

---

### 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,
  "has_password": true,
  "created_at": "2025-01-15T10:30:00+00:00",
  "last_login_at": "2025-06-01T14:22:00+00:00"
}
```

`has_password` reports whether the account has a stored password credential,
independently of any linked social provider. Password hashes are never returned.

**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/null | No | Future RFC3339 instant or date-only UTC end of day. Omitted, null or empty means creation time + 90 days. Stored and returned at millisecond precision. |
| `never_expires` | boolean | No | Explicitly select no expiry (default false); cannot be true with a nonempty `expires_at`. |
| `description` | string | No      | Optional description of key purpose          |
| `allowed_service_ids` | string[] | No | UserService IDs this key can proxy; omitted means empty. Incompatible with `allow_all_services: true`. |
| `allowed_node_ids` | string[] | No | Node IDs this key can route through; omitted means empty. Incompatible with `allow_all_nodes: true`. |
| `allow_all_services` | boolean | No | If true, key can access all user's external services (default: false) |
| `allow_all_nodes` | boolean | No | If true, key can route through all user's nodes (default: false) |

> New keys start with restricted service/node authority and a finite lifetime. An empty restricted list grants no resources. Broad grants and nonexpiry require explicit choices. Existing stored keys retain their policy, including legacy absent fields; rotation preserves that policy. See [issuance and rollout](API_KEY_ISSUANCE.md).

Explicit broad, nonexpiring key:

```json
{
  "name": "Production API Key",
  "scopes": "read write",
  "allow_all_services": true,
  "allow_all_nodes": true,
  "never_expires": true
}
```

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",
  "expires_at": null
}
```

**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 stored permissions and expiry (including nonexpiry). 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",
  "expires_at": null
}
```

**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`.                            |
| `auth_scheme` | string | No | Catalog bearer authorization scheme: an RFC 9110 token of 1–64 ASCII bytes. Omitted means `Bearer`. Valid only with bearer auth (including the `oauth2` alias). No user-connection override. |
| `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",
  "can_resync_identity": false
}
```

`can_resync_identity` says whether the caller may use
[`POST /api/v1/services/{service_id}/resync-identity`](#post-apiv1servicesservice_idresync-identity).
Only this endpoint computes it; list, create and update responses omit it.

**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)                           |
| `auth_scheme` | string or null | No | Replace the bearer scheme; `null` restores `Bearer`, omission preserves it. Catalog Managers follow own/shared row field rules; Tools Managers cannot set it. Admin Tool changes demote operations. |
| `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>"
```

---

#### POST /api/v1/services/{service_id}/resync-identity

Overwrite the identity-forwarding settings on every connection (`UserService`)
created from this catalog service with the service's current settings,
including connections whose settings were customized. The fields are
`identity_propagation_mode`, `identity_include_user_id`,
`identity_include_email`, `identity_include_name`, `identity_jwt_audience`,
`forward_access_token`, `inject_delegation_token` and `delegation_token_scope`.
Connections whose stored values already match are not rewritten, so their
`updated_at` and history are unchanged. It also clears a pending or failed
identity propagation marker on the service. It does not touch stored
credentials or anyone's sign-in with the downstream service.

Ordinary service edits (`PUT /api/v1/services/{service_id}`) already copy
identity changes to connections that still match the previous value, and skip
customized ones. Resync is the deliberate override for that drift.

**Auth:** First-party human session (API keys, service accounts, delegated and
relay tokens are refused). The caller must be allowed to change this service's
identity fields through `PUT /api/v1/services/{service_id}`: an Admin, or the
service's creator under the plain creator rule. Catalog Managers and Tools
Managers are refused because identity fields are Admin-only for them, including
on rows they created; person-owned rows are Admin-only. The service must be an
HTTP service. The write commits in one transaction that rechecks this authority
against the live service row.

**Response (200):**

```json
{
  "catalog_service_id": "d1e2f3a4-b5c6-7890-1234-567890abcdef",
  "matched_count": 37,
  "changed_count": 2,
  "affected_count": 2
}
```

| Field | Description |
|-------|-------------|
| `matched_count` | Connections to this service that were checked |
| `changed_count` | Connections whose settings differed and were rewritten |
| `affected_count` | Deprecated alias of `changed_count`. Earlier releases counted every connection here, changed or not |

The `catalog_identity_resync_succeeded` audit event records the actor,
`authority` (`admin` or `creator`), the field list, `matched_count` and
`changed_count`.

**Errors:**
- `1002 forbidden` -- Not a first-party human session, or not allowed to change this service's identity fields
- `1003 not_found` -- Service does not exist
- `1000 bad_request` -- The service is not an HTTP service
- `1004 conflict` -- The service's authority or identity settings changed while the request ran; reload and retry

**CLI:** `nyxid catalog resync-identity <SERVICE_ID_OR_SLUG> [--yes] [--output json]`

**Example:**

```bash
curl -X POST http://localhost:3001/api/v1/services/d1e2f3a4-b5c6-7890-1234-567890abcdef/resync-identity \
  -H "Authorization: Bearer <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.

NyxBot callers retain these routes under the existing permission modes. Exact
certificate/session admission binds the connection (or existing catalog-only
authority), requested parameters and bounded lifetime. Organization use asks in
Auto and Ask every time; Full access admits without a prompt. Retry the same
request with `X-NyxID-Acknowledgement-Id` after allowing its action card. A tunnel
or terminal card authorizes that one session's dynamic traffic, with live
revocation checks; it does not represent per-frame approval. See
[NyxBot service execution](NYXBOT_SERVICE_EXECUTION.md).

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.
- Service selection applies authority before same-slug collision resolution. Organization specialist catalogs contain only connections from the bound organization that the live member ACL permits; an ungranted row may be listed with `chat_access: acknowledgement_required` and is then handled by the existing service gate. `nyx__list_connected_services` rows for user services include `owner_kind` (`personal` or `organization`), and `nyx__search_tools` accepts an exact connection ID query and includes `service_id` in each service match.

`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,
    "shadowed_connections": 0
  }
}
```

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, invalid visible operation contracts, and caller-authorized same-slug connections omitted by precedence (`shadowed_connections`) 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,
      "authorization_nonce_required": 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`)                |
| `authorization_nonce_required` | boolean | No | Default `false`; generate a fresh nonce for each hosted OAuth2 authorization-code attempt. See the hosted nonce contract below. |
| `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                                           |

**Hosted authorization nonce contract:** `authorization_nonce_required` is additive and default-off. Omitted create values become `false`; omitted updates preserve the stored value. Responses include the setting; consumers of older servers should treat a missing response field as `false`. Explicit `true` is rejected for provider types other than `oauth2`; missing/false remain valid. It is a client-bound OAuth setting under the existing Admin/Catalog Manager permission rules.

When explicitly enabled, NyxID generates 32 cryptographically random bytes, encodes them as URL-safe base64 without padding, stores the value separately as `OAuthState.authorization_nonce`, and sends exactly that value once as `nonce` on the hosted OAuth2 authorization request. It is independent of OAuth state, PKCE and ChatConnect popup correlation. Enabled configurations reject authorization URLs containing a `nonce` query parameter (including a percent-encoded key) or a fragment, and reject `client_id_param_name` equal to `nonce` after trimming. Validation applies to the effective configuration on later URL/parameter edits too. `extra_auth_params` cannot override nonce, state or PKCE.

This capability applies only to hosted OAuth2 authorization-code initiation, including ChatConnect and hosted connect links; node-owned OAuth and public login/OIDC have separate flows. Callback handling does not require a nonce or consume external ID tokens. Attempts started before activation remain valid, including legacy states without this field. Code exchange, refresh and revocation requests are unchanged; existing tokens need no migration or reconnection solely for this setting.

Upgrade **all backend replicas before activation**: older initiators ignore the capability. Configure Hubstaff explicitly after upgrade while retaining `hubstaff:read`, PKCE S256 and the existing client authentication. No `openid` scope or provider-slug inference is needed. This contract does not establish live Hubstaff validation.

**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                                    |
| `authorization_nonce_required` | boolean | No | Set or clear the hosted OAuth2 authorization nonce capability. Omission preserves the stored setting. |
| `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)

Connected-service health/readiness is exposed through the five fixed
`/api/v1/keys/{id}/monitoring` routes. See [Service monitoring](SERVICE_MONITORING.md)
for payloads, caller-token authority, revisions, timeouts and deployment requirements.
The default-off `services:monitoring` flag resolves for the acting person,
including live organization overrides. When off, every route returns a generic
404 `not_found` before any service lookup or chrono-probe call; the frontend
hides the section without requesting it. When on but `CHRONO_PROBE_URL` is unset
or invalid, routes return 404 `monitoring_not_configured` (13301) and the UI hides
the section. A configured upstream failure returns 503 `monitoring_unavailable`
(13300). Explicit Check now and draft checks use the normal proxy with the
caller's authority: **All requests** approval settings prompt per check, and a
priced platform service bills each check to the caller. Status reads do not run
checks.


#### Agent discovery order per service group

`GET /api/v1/service-preferences` returns only `{ "groups": [{ "group":
"catalog:<catalog UUID>", "ordered": ["<UserService UUID>"] }], "version": 3,
"updated_at": "<RFC3339>" }`. A missing document returns `groups: []`, version 0
and a null timestamp. IDs are filtered through live owner, organization and
service-scope visibility before grouping. Custom `connection:` singleton groups
are omitted. No stored, hidden or capacity counts are returned. General API keys
and delegated exact `account:read` GETs may read authorized metadata; service
accounts and relay tokens cannot read this route.

`PUT /api/v1/service-preferences/groups/{group}` accepts only `{ "ordered": [...],
"expected_version": 3 }`. `group` must be `catalog:<canonical lowercase RFC-variant UUID>` with a recognized version (1–8, including the existing v4/v5 catalogs); nil/max and unknown versions are rejected;
connection IDs must be canonical lowercase RFC4122 UUID v4 strings, unique,
authorized members of that group and at most 200. `ordered: []` explicitly resets
this group's currently authorized order to default. A nonempty submission appends
any stored, currently authorized group IDs omitted by a stale draft in their
previous relative order. The server replaces only this group's visible occupied
slots; additional IDs follow its last slot. All unrelated, hidden and stale IDs
and their relative order remain unchanged. A logically identical group order is a
no-op even when its stored IDs are interleaved with other groups.

The resulting account document may contain at most 200 IDs across all services.
Capacity returns an actionable generic 400: reset another service or explicitly
release unavailable preferences. It reveals no hidden IDs or counts. Resets work
at capacity. No save or read automatically prunes storage.

`DELETE /api/v1/service-preferences/hidden` accepts only `{ "expected_version": 3 }`
and explicitly releases stored IDs outside the actor's current authorized
inventory, including deleted or lost-access organization connections. Accessible
custom singleton IDs and disabled rows are retained, as are every visible group's
relative order. If access returns, released orders must be set again. The CLI and
inline capacity banner require explicit confirmation before this action.

Both writes require a verified first-party human session/access token. API keys,
delegated tokens, service accounts, relay and OAuth application tokens cannot
write. Both enforce 16 KiB bodies, reject unknown fields and accept expected
versions 0 through 9007199254740990. Invalid input returns 400; stale versions or
insert/CAS races return 409 (`Conflict`, code 1004). Changed writes increment the
version with BSON-millisecond timestamps and chained audits: scoped saves include
only `{group, count, version}`; releases include only `{released_hidden, version}`.
No-op writes retain metadata and produce no audit.

`GET /keys` and `GET /keys/{id_or_slug}` add `preference_rank`, a dense 1-based rank
within the authorized active HTTP catalog group, and `preference_position`, the
saved position among authorized stored group IDs including disabled rows. Both
are null for custom singleton groups; disabled rows have a null discovery rank.
The CLI hidden-release command requires verified HTTPS remotely, refuses
redirects on reads, refresh and DELETE (including retry), and preserves its
existing profile/identity and caller-selected-credential fences. Local HTTP is
limited to exact localhost/127.0.0.1/[::1] destinations, bypasses proxies and pins
localhost to loopback. Other transport helpers retain their existing behavior.

The UI shows `Discovery #n` and `Saved #p · disabled` separately. Restricted MCP
callers see dense ranks over their own fully scoped discovery inventory, which
can differ from the owner's REST pills. Preference never changes named execution,
retries, pools, grants, approvals, authority digests, billing or `/mcp/config`.
Part A also leaves implicit LLM gateway connection selection unchanged.


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 |
| `icon_url` | URL string, omitted | Per-connection icon override set by the user |
| `catalog_icon_url` | URL string, omitted | The catalog service's icon (its provider's uploaded icon, or a Tool's own icon); clients show it when there is no `icon_url` override |
| `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 16 KiB before trimming or deduplication (including the spaces inserted between array entries), at most 256 bytes per scope, and only `[A-Za-z0-9._:/~+*=-]` characters. There is no scope-count cap. 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. OAuth initiation uses query parameters; proxy request-line limits and upstream authorization-URL limits can reject large scope lists below the parser's byte bound.

`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` | Literal, case-insensitive search over connection and original catalog service names and slugs, 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.
The connection `name` and name search use the same label as the Services page:
the owned stored key's label, falling back to the owned endpoint label and then
the connection slug. Explicit platform bindings use the endpoint label even
when a personal key is retained. Connection-label lookups project only IDs and labels.

Candidates also carry `catalog_service_id`, `group_name`, and `group_slug` for
grouped connection selectors. Catalog-backed connections use the original
service's name and slug; group them by `catalog_service_id`, since different
services can share a display name. Custom connections have a null catalog ID,
`group_name: "Custom connections"`, and a null `group_slug`. Group metadata
describes only the returned connections; pagination still counts connections,
and one service's connections may span multiple pages.

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.

### Managed Execution Status

The Telnyx platform offering reserves NyxID credits before provider dispatch and
settles validated token usage. These authenticated reads expose execution
metadata without prompts, completions, provider credentials, or raw usage
responses. Existing credential-type and scope checks still apply. A person can
read their own acting executions and liabilities funded by their personal
wallet, including their service accounts; a service account can see only its
own acting executions. There is no caller-selected billing owner.

#### GET /api/v1/billing/executions

**Auth: Required.** Returns a JSON array of the latest 50 visible executions,
ordered by descending `created_at` and then descending ID. It accepts no
pagination or owner selection parameters.

#### GET /api/v1/billing/executions/{id}

**Auth: Required.** Returns one visible execution. An invalid UUID, absent row,
or inaccessible execution returns `404`.

Both endpoints use this metadata shape:

```json
{
  "id": "0e8569b5-16ba-4205-a91f-047ace6c6588",
  "service_slug": "telnyx-platform",
  "model": "THE_VERIFIED_MODEL_ID",
  "state": "pending",
  "maximum_credits": "0.001",
  "pending_reason": "outcome_unknown",
  "created_at": "2026-10-16T00:00:00Z",
  "updated_at": "2026-10-16T00:00:01Z"
}
```

`maximum_credits` is an exact decimal string containing the reservation ceiling.
`service_slug` and `pending_reason` may be null. States are `prepared`, `funded`,
`dispatch_admitted`, `pending`, `evidence_ready`, `cancelling`, `released`, and
`settled`. A pending execution retains possible liability; reading its status
does not replay the provider call or resolve missing evidence. Successful HTTP
execution responses include `X-NyxID-Execution-Id`; uncertain outcomes return
`managed_execution_pending` with the UUID in the error message.

See [Telnyx platform billing](TELNYX_PLATFORM_BILLING.md) for the supported
operation, funding behavior, activation requirements, and recovery limits.

### 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:** When the resolved approval policy requires approval and the request uses a non-session auth method (API key, delegated token, service account, or access token), the proxy checks for an existing grant in grant mode. Otherwise it persists a pending request and **holds the HTTP connection open** until approval, rejection, or timeout. Notification delivery is attempted when configured; an unavailable provider or missing channel never authorizes execution. Review and decide pending requests in `/approvals/history`, using **Refresh** to discover requests created after the page opened. Approved requests proceed; rejection or timeout returns `403 Forbidden`. An absent global preference uses **Writes only**: read-class operations proceed without approval, while write and destructive operations require it. Explicit stored true selects **All requests** and false selects **Off**; existing booleans keep their meaning. Lazy notification settings creation preserves the absent preference. The implicit global default exempts auto-connected (auto-provisioned, credential-free) services; explicit per-service and org `ServiceApprovalConfig` policies retain their precedence and existing grant semantics. Direct browser sessions (session cookie auth) bypass approval requirements; explicit Deny rules still refuse execution. Upgrade and drain all serving replicas and participating workers before relying on this contract; see [security rollout readiness](SECURITY_ROLLOUT_READINESS.md).

**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`.

The service root accepts both `/api/v1/proxy/s/{slug}` and `/api/v1/proxy/s/{slug}/`; both forward `/` to the service. The UUID route (`/api/v1/proxy/{service_id}` and `/api/v1/proxy/{service_id}/`) and the public route (`/public/s/{slug}` and `/public/s/{slug}/`) behave the same way.

**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:** LLM gateway endpoints share the blocking approval flow described under [Proxy](#proxy). Required programmatic requests wait for approval, rejection, or expiry independently of notification availability. The unset **Writes only** preference allows read-class generation under the catalog inference metadata and closed stateless request contract. Provider storage, resource effects and unknown request extensions remain writes. Explicit true still gates reads and explicit false allows writes; explicit per-service/org policies, auto-connected exemptions and grant semantics retain their documented behavior. Pending requests remain available in web Approval History when delivery is unavailable.

#### 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. Access JWT authentication also checks the live active user, with additional session and token-class fences. First-party session revocation applies immediately to NyxID requests. Ordinary OAuth client access tokens currently have a consent-revocation window until expiry (default 15 minutes plus configured verification leeway); external relying parties validating offline cannot observe immediate database revocation. Token expiry and supported remote-provider revocation are separate lifecycle effects.

**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

MFA enrollment is a first-party human operation. Browser sessions and first-party
access tokens may call this route; API keys, service-account tokens, delegated
tokens, and relay tokens are rejected. Successful confirmation keeps the current
session and revokes other sessions, refresh tokens, and session-fallback MCP rows.

**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"}'
```

#### POST /api/v1/auth/mfa/verify

Redeem a five-minute first-factor challenge with a TOTP or single-use recovery
code. Password login and token clients send `mfa_token` in the JSON body. A web
social login may omit it: the server reads the HttpOnly `nyx_mfa_challenge`
cookie instead. Success issues the normal browser cookie or token response and
clears the challenge cookie. The cookie value is never placed in a URL.

```json
{ "code": "123456", "client": "web" }
```

Expired, cancelled, unknown, exhausted and already consumed challenges return HTTP 401
with `details.reason: "mfa_challenge_expired"` and clear the challenge cookie.
A wrong code on a live challenge keeps the cookie and spends the existing attempt budget.
Clients return to sign-in after terminal failures. The web form explicitly offers recovery codes.

When `auth:mobile-mfa` is enabled for the signing-in person, social id_token exchange (Google/GitHub/Apple native-mobile flow) at `/oauth/token` uses OAuth error JSON (HTTP 400):

```json
{ "error": "mfa_required", "error_description": "MFA required", "error_code": 2002, "session_token": "<five-minute-challenge>" }
```

No access/refresh token or session is issued in that response. Send `session_token`
as `mfa_token` with `code` and `client: "token"` (or `"mobile"`) to MFA verify.
Password login keeps its existing HTTP 403 error code 2002 response.

The default-off flag skips the social token-exchange MFA challenge and persists a mobile-exempt session. Password login, including `client: "mobile"`, always retains MFA. No environment variable controls this flag.

Skipped mobile MFA records metadata-only `mfa: skipped_mobile_rollout` in the `social_login` audit for redirect sign-in or the `social_token_exchange` audit for native exchange. Both paths also emit `auth.mobile_mfa_exempted` through the existing telemetry consent gates.

Completed legacy sessions with absent/null assurance and mobile-exempt sessions keep authenticating through cookie, bearer, refresh and MCP fallback until normal expiry/revocation. Parent-less legacy MCP fallback for MFA accounts has a fixed 30-day bound from creation, independent of its sliding idle expiry. Explicit unverified sessions are rejected for MFA accounts. A sid-less legacy first-party refresh acquires a fixed 30-day session on first refresh; successors cannot extend its expiry. In-flight legacy device codes, login codes and approvals without assurance fail closed.

Third-party OAuth authorize/consent is SSO from existing IdP authority and accepts legacy/mobile-exempt sessions. Account management, such as API-key management, is also not a NyxID sign-in derivation. A new NyxID sign-in derived from an existing device requires verified authority for an MFA account.

#### POST /api/v1/auth/mfa/step-up

Verify the **current** session before authorizing a sign-in on another device.

**Auth:** First-party human cookie session or first-party bearer with `sid`. API keys, service accounts, delegated/relay and OAuth-client tokens receive the standard HTTP 403 credential-type denial. Sid-less bearers cannot step up.

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

Accepts TOTP or a single-use recovery code using the login verifier, replay protection and shared per-account rate budget (10 attempts per 300 seconds). Success atomically sets verified assurance and removes any exemption from this live session, with a metadata-only `mfa_step_up` audit. It does not issue tokens or extend expiry.

**Response (200):** `{ "message": "Session verified" }`.

**Errors:** HTTP 400 for MFA not enabled or wrong/replayed/consumed codes; HTTP 429 when the shared verification budget is exhausted; HTTP 401 for expired/revoked session authority.

For MFA accounts, device approval, Agent Key approval, login-code minting, CLI-token and app identity approval from legacy/mobile-exempt authority return:

```json
{
  "error": "mfa_step_up_required",
  "error_code": 2003,
  "message": "Approving sign-ins on other devices requires MFA. Verify this session with your authenticator, or approve from a device where you signed in with MFA."
}
```

This is HTTP 403 and does not expire the approver session. Verify through step-up and retry the original action. Web shows an inline authenticator/recovery prompt; mobile shows it only when `/users/me.capabilities.enabled_features` includes `auth:mobile-mfa`, otherwise it directs the user to the NyxID website to verify and approve or create a login code. Enrollment continues to verify the current session and sign out other devices.

Requester-side device polls and browser handoff creation return terminal `auth_device_access_denied` (403 / 11204) when an old approval lacks verified authority; the browser stops polling and shows a denied request. Start a new request after verifying the approver. The CLI explicitly handles `mfa_step_up_required` with exit code 23 for login-code redemption of an old in-flight code; generate a new code from a verified session.

#### POST /api/v1/auth/mfa/cancel

Abandon a pending browser challenge. This deletes the challenge and clears the
`nyx_mfa_challenge` cookie. It is safe to call after expiry or a replay.

#### POST /api/v1/auth/mfa/disable

Disable MFA after proving a current factor. Every account must send `code`; a
password-backed account must also send its current `password` (including social-linked accounts that retain one). `GET /users/me` reports `has_password` for this decision. Social-only
accounts omit `password`. Recovery codes are consumed when used for disable.

```json
{ "code": "123456", "password": "current-password" }
```

The route is first-party human only and applies the same rate limits and account
state fencing as login MFA.

---

### 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

Admin endpoints require the authenticated user to hold the applicable platform or scoped permission described for each route. Admin user management includes self-protection: admins cannot change their own role, disable themselves, or delete themselves.

#### Feature flag roles and management

The system roles `feature-flag-operator` and `feature-flag-admin` can be assigned
to any user through the existing user role assignments or through a group.
They grant only feature flag administration; neither role grants access to
unrelated admin pages or the admin user directory.

| Caller | List flags | Create flags | Edit rollout and metadata |
| --- | --- | --- | --- |
| Platform Admin | All | Yes | All |
| Platform Operator | All | No | No |
| `feature-flag-operator` | Flags they created | Yes | Flags they created |
| `feature-flag-admin` | All | Yes | All |

Permissions combine: a Platform Operator who also holds `feature-flag-operator`
retains the platform-wide read permission but can write only their own flags.
Feature flag admin access wins when both feature flag roles are held.
Authorization resolves current direct and group roles on every API request.

The roles carry `nyxid:feature_flags:own:write` and
`nyxid:feature_flags:admin`, respectively. Startup seeds both as non-default,
protected system roles. A pre-existing custom/client role with the same slug is
left untouched so existing assignments never acquire permissions implicitly.

`GET /api/v1/admin/feature-flags` merges built-in code definitions and runtime
flags, filtering the list to the caller's read scope. Each flag includes additive
`created_by` (null for built-ins) and `can_edit` fields. Runtime creator identity
is immutable; changing or clearing the free-text `owner` does not change access.
Built-in keys are reserved and cannot be claimed through creation.

`POST /api/v1/admin/feature-flags` creates a runtime flag:

```json
{
  "key": "my-team:new-feature",
  "description": "Enables the new feature for our rollout.",
  "default_enabled": false
}
```

Keys are 1–128 ASCII lowercase letters, digits, colons, underscores or hyphens,
starting with a letter or digit. Descriptions are required and limited to 512
characters after trimming. `default_enabled` defaults to false. Unknown fields
are rejected. The server binds `created_by` to the authenticated user, persists a
UUID v4 definition in `feature_flag_definitions`, and returns 201 with `key` and
`created_by`. Duplicate built-in or runtime keys return 409.

Runtime flags use the existing global, organization, and personal override
precedence and appear in resolved `enabled_features` on `/users/me` and org
responses. Creating a flag makes it available for consumers to use its key;
application behavior still requires a consumer for that key. Built-in definitions
win if a later deployment introduces the same key. Overrides and metadata bind
runtime definition UUIDs separately from built-ins, so old settings never carry
across that boundary or from a retired built-in into a newly created flag.
Replacement unique indexes include that identity and are created before the
legacy indexes are retired.

Deploy the backend before the frontend so `/admin/feature-flag-targets` is
available when the updated rollout picker starts using it. Upgrade all backend
replicas before creating runtime keys that match retired
built-ins. Older binaries recreate the legacy unique indexes on startup. Before
rolling back to such a binary, remove any rows split across definition identities
for the same key and target. A runtime definition shadowed by a built-in remains
stored and becomes visible again if that built-in is retired; retirement cleanup
can remove the runtime definition and its identity-bound settings when needed.

Existing `PUT /api/v1/admin/feature-flags/{flag_key}` and `DELETE` at the same
path set and clear rollout overrides. Metadata PUT/PATCH retain their existing
contracts. Every write checks the caller's permission and, for operators, the
immutable creator. `DELETE` clears an override; it does not remove the definition.

`GET /api/v1/admin/feature-flag-targets` supplies bounded rollout suggestions
without granting access to `/admin/users`. It requires `flag_key` naming an
editable flag and `kind=person|org`; optional `search` is a literal, case-insensitive
email/name/slug match (max 128 bytes), and `limit` is clamped to 1–20. Results
contain only active accounts with `id`, `email`, nullable `display_name`, and
nullable `slug`. A caller who cannot edit the referenced flag receives 403.
Successful searches emit metadata-only audit events containing the flag key and
target kind. Creation and existing writes retain audit events.

`GET /users/me` includes `capabilities.read_feature_flags`,
`create_feature_flags`, and `manage_all_feature_flags`. The admin navigation and
route guard expose `/admin/feature-flags` to these role holders without opening
other admin pages. The page uses each flag's `can_edit` for write controls.

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

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

**Auth:** Platform Admin, feature flag Admin, or feature flag Operator for a flag they created

| 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. |
| `group` | string/null | No | Up to 80 characters; null or trimmed blank restores namespace grouping. |
| `tags` | string array | No | Replaces tags; `[]` clears. Up to 12 tags, each 1–40 lowercase letters, digits, hyphens or underscores, starting with a letter or digit. Trimmed, lowercased, sorted and deduplicated. Null is rejected. |
| `expected_tags` | string array | No | Optional saved tag baseline. A mismatch returns 409, preventing an unseen concurrent tag edit from being overwritten. |
| `sunset` | boolean | No | Hides the flag in the UI's default Active view. Never changes evaluation, defaults, or overrides. Null is rejected. |

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`, nullable
`group`, `tags`, `sunset`, and nullable `metadata_updated_at` / `metadata_updated_by`.

For example, `{"owner":"Identity team"}` changes only the owner. The existing
`PUT` route at this path replaces description and owner, preserving group, tags,
and sunset. Clients that need sparse updates should use `PATCH`.

#### GET /api/v1/admin/feature-flags/{flag_key}/history

Uses the flag list's authorization: platform readers can read all histories;
feature flag operators can read histories only for flags they created. Does not
grant access to the general audit log or user directory.

Returns up to 25 recorded changes, newest first. Optional `before` is the opaque
`next_cursor` from a previous response; cursors use `(created_at, _id)` so new
writes do not shift older pages. Each entry includes actor ID/name, event
type, timestamp, and flag-specific details. Emails are available only to platform
readers with read-all access. Rollout targets include a current display name or
slug when available and retain the recorded scope and ID. New writes include before/after
values for rollout and metadata. Unknown fields
from the audit payload are excluded. `origin` reports the runtime definition's
authoritative creator and creation timestamp even when its old audit entry is
missing. Built-in origins are declared in code.

Admin creation, override changes/removals, and metadata edits commit with their
actor-attributed audit entry in one MongoDB transaction. An audit failure rolls
back the change. No-op writes leave attribution and timestamps untouched and do
not append a change event. Sunset flags remain
in the list API, resolve normally, and retain editable rollout/history.

History respects runtime definition identity. Legacy events lacking that identity
are inferred using the persisted runtime creation timestamp. For a built-in
shadowing a runtime key, ambiguous legacy entries are omitted and
`legacy_ambiguous_omitted` is true. Such historical rows cannot be reconstructed
when they were never recorded. Code deployments, startup migrations and org
removal cascades remain outside this per-flag admin history.

Deployment creates the partial `flag_history` audit index for rows containing
`event_data.flag_key`; startup waits for this index build. Deploy the backend
on every replica before the new frontend, which writes the additive metadata fields and calls
the new history route. MongoDB must support transactions, as required by other
admin policy writes.

---

#### 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 Usage

Platform-wide usage reports live under `/api/v1/admin/usage`
(`GET /admin/usage`, `GET /admin/usage/analytics`,
`GET /admin/usage/identities`, and `GET`/`PUT /admin/usage/workspace`). The
full query and response contract is in
[BILLING_ANALYTICS.md](BILLING_ANALYTICS.md#api-and-reporting-semantics).

**Auth:** Admin or Operator, or any user holding the
`nyxid:admin:usage:read` permission through a direct or group role. The seeded
system role **Usage Viewer** (`usage_viewer`) carries it; assign it with
`POST /api/v1/admin/users/{user_id}/roles/{role_id}` or add the permission to a
custom role. Holders get read-only access: `PUT /admin/usage/workspace` stays
admin-only. `GET /api/v1/users/me` reports the result as
`capabilities.read_admin_usage`.

#### GET /api/v1/admin/assistant/model-usage

Returns attributed NyxBot and specialist model costs, requests, and provider
token counts, with daily UTC series and top billing accounts. Same read access
as Admin Usage: Admin, Operator, or the `nyxid:admin:usage:read` permission
(Usage Viewer). `GET /api/v1/admin/assistant/analytics` and
`GET /api/v1/admin/assistant/feedback`, which back the rest of the Usage ->
NyxBot tab, use the same check.

Use `from` and `to` RFC 3339 timestamps for a positive window of at most 31 days.
An optional `model` selects an exact, case-sensitive billing model (trimmed,
1–256 characters); `unknown_model=true` selects missing model identities and
cannot be combined with `model`.

The response contains `window`, `freshness`, `totals`, `models`, `daily`,
`accounts`, `other_accounts`, `services`, and `excluded`. `services` breaks
model executions down by inference service (Top 20 plus a summed Other row with
`service: null`); the service is recorded on every execution, including those
whose model is unknown. Costs are exact decimal credit
strings or null. Top 20 models and Top 10 accounts include summed Other usage;
account rows include their own model breakdown. Excluded populations disclose
orchestration, ordinary tools, unclassified assistant activity, and historical
platform records without provable attribution. See the full
[reporting contract](BILLING_ANALYTICS.md#nyxbot-model-usage).

**Errors:** `400` invalid window or model filter; `403` without Admin, Operator,
or `nyxid:admin:usage:read` access; `503` (`12200`) when the bounded report
times out.

#### GET /api/v1/admin/usage/identities

Options for the Usage page's actor/owner filters, or labels for saved filter
ids. Returns only `id`, `label` and optional `detail` (email, `Organization` or
`Service account`).

| Parameter | Type   | Description                                                             |
|-----------|--------|-------------------------------------------------------------------------|
| `kind`    | string | `actors` (people and service accounts) or `owners` (also organizations) |
| `search`  | string | Case-insensitive substring                                              |
| `ids`     | string | Comma-separated ids (at most 100) to label instead of searching         |

Admins and Operators search the whole directory. Callers with only the usage
permission see only identities recorded in the usage rollups, and the List
report redacts its `selected_user` unless that identity appears in the report.

```json
{
  "options": [
    { "id": "550e8400-e29b-41d4-a716-446655440000", "label": "Jane Doe", "detail": "jane@example.com" }
  ],
  "total": 1
}
```

**Errors:** `400` invalid `kind` or more than 100 `ids`; `403` without usage
access; `503` (`12200`) when the lookup times out.

---

### 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.

---

## Security Rollout Readiness

```
GET /api/v1/admin/security-readiness
Authorization: Bearer <admin_or_operator_access_token>
```

Returns a map keyed by security capability. Each report includes `ready`,
`blockers`, `expected_replicas`, `live_generations`,
`platform_policy_required`, `catalog_missing_policy`, and
`catalog_explicit_empty_policy`. Catalog counts apply to the platform-policy
capability. Missing, duplicate, stale, unsupported or differently configured
serving processes block activation (`ready` keeps its strict meaning).
Additive `activated` / `active_since` show durable prior clean readiness;
`serving_ready`, `serving_with_roster_warnings`, `roster_warnings` and
`serving_blockers` explain continued serving separately. An activated capability
may serve with roster warnings only while every live generation supports it and
all hard checks pass. New activation remains strict. Refused gates return
`503 security_readiness_unavailable` (code `12900`); ordinary flag reads retain
their resolved boolean. The map includes `automation:coordinator-completion-v2`
even when optional automation enrollment is disabled.

| Additive field | JSON type | Nullable | Meaning |
| --- | --- | --- | --- |
| `activated` | boolean | No | Durable evidence of a prior clean assessment exists. |
| `active_since` | RFC 3339 UTC string | Yes | First recorded activation time, or null when not recorded. |
| `serving_ready` | boolean | No | Current traffic may serve, including recorded activation with only roster warnings. |
| `serving_with_roster_warnings` | boolean | No | Serving is permitted despite one or more roster warnings. |
| `roster_warnings` | array of strings | No | Sorted tolerable roster blocker strings, also present when hard checks refuse serving. |
| `serving_blockers` | array of strings | No | Sorted hard serving blockers; includes `capability_not_activated` when strict readiness fails without evidence. |

This endpoint requires admin/operator access and is separate from public
`/health`. Roster/drain declarations are operational prerequisites; the
`approval:required-web-v1` report is diagnostic and does not fence old serving
replicas. See [security rollout readiness](SECURITY_ROLLOUT_READINESS.md) for
configuration, stored-policy boundaries and sticky platform cutover/recovery.

---

## Notification Settings

Manage notification channels and approval preferences. All endpoints require authentication (human-only, no service accounts or delegated tokens).

GET/PUT settings also expose additive `group_mentions_enabled` (boolean, default
`true` for legacy absent fields; omitted PUT preserves the preference). This
controls **Mentions in groups** pushes through registered FCM/APNs devices and
also requires `push_enabled`. It does not disable in-app unread/mention counts.
Mention pushes omit transcript previews, coalesce per person/group for five
minutes, and deep-link to the collaboration group; no Telegram or email is sent.
Collaboration responses include optional `last_seen_seq`, `unread_count`, and
`mention_count` inside `collaboration`. Human participants advance the marker
with `POST /api/v1/assistant/nyxagent/groups/{id}/read` and
`{"last_seen_seq": 42}` (204). The server clamps to existing history and never
moves the marker backwards. Nonparticipants receive not-found. New writes and
pushes require the sharing flag and collaboration readiness gate.

### 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,
  "global_approval_mode": "writes_only",
  "approval_required": true,
  "approval_suspended": false,
  "approval_delivery_configured": true,
  "approval_web_available": true,
  "approval_timeout_secs": 30,
  "grant_expiry_days": 30
}
```

`global_approval_mode` is `writes_only` (the unset default), `all`, or `off`.
Writes only requires approval for write and destructive operations and allows reads;
All requests requires approval for every verb; Off removes only the global fallback.
Explicit per-service rules and organization policies retain their precedence.
The compatibility boolean `approval_required` is true for writes-only and all;
clients must use `global_approval_mode` to distinguish them. Older servers omit
that field: a stored/returned true means All requests, and false means Off.

New channels leave the stored preference absent and use a 300-second timeout.
Lazy settings reads and tool-approval creation never choose a preference. Stored
true/false rows retain their exact behavior, including rows from the unreleased
W9.3 lazy-creation build. They have no reliable provenance marker and are never
silently reset. An owner can explicitly select Writes only to clear the choice.
A missing preference on any row means writes-only; existing timeout values and
the legacy missing-timeout default of 30 seconds remain unchanged.

Approval enforcement is independent of notification delivery. This server returns
`approval_suspended: false` and `approval_web_available: true`: pending requests
can be decided in Approval History without Telegram or push.
`approval_delivery_configured` reports enabled registration plus initialized
provider configuration; it does not promise a successful send. Older servers may
omit these fields or report suspension, so clients retain cautious channel guidance.
Upgrade and drain every old replica before relying on write approval for new
users; see [security rollout readiness](SECURITY_ROLLOUT_READINESS.md).


**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,
  "global_approval_mode": "writes_only",
  "approval_timeout_secs": 60,
  "grant_expiry_days": 14
}
```

All fields are optional. Only provided fields are updated. `global_approval_mode`
accepts `writes_only`, `all`, or `off`. Selecting `writes_only` clears the stored
boolean. The legacy `approval_required` write remains supported: true selects
All requests, false selects Off. Conflicting mode/boolean writes return 400;
omitting both preserves the current choice. The authorization evidence endpoint
also includes `global_approval_mode`.

**Validation:**
- `approval_timeout_secs`: 10..=300
- `grant_expiry_days`: 1..=365
- `telegram_enabled: true` requires a linked Telegram account
- `approval_required: true` can be enabled with no external notification channel. Pending requests wait for a web decision or expire without executing.

**Response (200):**

```json
{
  "telegram_connected": true,
  "telegram_username": "johndoe",
  "telegram_enabled": true,
  "push_enabled": true,
  "push_device_count": 1,
  "global_approval_mode": "writes_only",
  "approval_required": true,
  "approval_suspended": false,
  "approval_delivery_configured": true,
  "approval_web_available": true,
  "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 remains required and no configured delivery remains, the response directs the user to Approval History on the web. Disconnecting Telegram does not suspend required approval.

**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. It adds a notification route; required approval is already enforced independently of that route, and provider configuration does not guarantee successful delivery.

**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 remains required and no configured delivery remains, the response directs the user to Approval History on the web. Removing the last device does not suspend required approval.

**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
```

### Decide an assistant execution permission (default off)

`POST /api/v1/approvals/requests/{request_id}/execution-decision` is a dedicated
first-party-human endpoint for `execution_proposal` cards. The body contains
`approved`, `expected_revision`, `choice_id`, `choice_digest`, and an
`idempotency_key`; denial uses null choice fields. Operation is the default.
The response is the current approval-request DTO, including the additive proposal
review and independent operation status. A saved permission is not proof that the
provider call completed. The server resumes the retained effect; clients must not
reconstruct or automatically retry it.

Only enrolled assistant MCP/proxy sources with live server task lineage create
these cards. The authoring readiness capability is required, along with reader
and dispatch readiness; enrollment is per-person only. The legacy `/decide` path
refuses every proposal before mutation. Card detail and approved scope/input
review are visible only to the acting first-party human, including requester-only
group cards. Existing list/revoke routes manage the resulting execution grants.
Mobile/Telegram offer a web link. See [execution permissions](EXECUTION_PERMISSIONS.md#permission-updates-and-resume-2195-part-a)
for supported request shapes, four validity choices, encrypted retention limits
and crash/recovery behavior. Existing legacy requests keep their semantics.

### 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 (the global fallback retains the auto-connected exemption; delivery never suspends approval).

**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 (the global fallback retains the auto-connected exemption; delivery never suspends approval).

**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 retains the auto-connected exemption; delivery never suspends approval).

**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.

## Channel bot health

`GET /api/v1/channel-bots/{id}/health` returns metadata-only delivery diagnostics for anyone who can read the bot:
- `diagnostics`: inbound, reply and webhook timestamps and errors, `subscription_state`, `consecutive_errors` and the stable `failure_reason`;
- `mode` (`webhook` or `poll`);
- the stable `recommended_action` (`none`, `reconnect`, `resubscribe`, `verify`, `wait_rate_limit`, `enable_billing`, `contact_admin`, `gateway`) and `recommended_action_text`;
- `can_write`.

Discord responses also include optional `discord_intake`: receiving side
(`nyxid_relay`, `native_gateway`, or intentional `interactions_only`),
observed state, stable code/block reason, hand-over time when known, and last
authenticated inbound (binding-scoped for native intake). The admin health/list endpoints and
NyxBot channel listing expose the same evidence. Native `selected` without a
confirmed event is unconfirmed, not healthy; see [Discord intake health](CHANNEL_BOT_RELAY.md#discord-intake-health-and-failed-hand-overs-2328-2323).

Unauthorized callers get the not-found shape.

`POST /api/v1/channel-bots/{id}/resubscribe` needs write access and is X-only. It re-registers the X Activity subscription, reads it back live, records a `channel_bot_resubscribed` audit row, and returns fresh health.

Admins can use `GET /api/v1/admin/channel-bots` (`platform`, `status`, `limit` 1-500, `offset`; ordered by id), `GET /api/v1/admin/channel-bots/{id}/health` and `GET /api/v1/admin/channel-bots/webhook-rejections`. The last returns per-platform counters of deliveries refused before a bot was authenticated.

All of these routes are denied to delegated `account:read` tokens. Failure codes and recovery are described in [X channel workflow, health and recovery](CHANNEL_BOT_RELAY.md#x-channel-workflow-health-and-recovery).

## 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 |
| POST | `/channel-bots/telegram-new/requests/{id}/creation-link` | Human-only, empty body; issue a native creation form URL for the same eligible bound request |
| 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`.

Creation-link responses contain `{request, creation_url}` with `no-store`/`no-referrer` headers and share the five-per-minute actor mutation limit. The server validates live owner, manager, expiry and exact saved hosted provenance. Legacy requests without explicit origin and platform-installation requests are ineligible. Request responses add optional `prompt_delivery` (safe phase/outcome/timestamps and bounded numeric diagnostics) and advisory `can_open_creation_form`. Accepted delivery does not prove rendering, creation or an agent reply. Recovery retains the request ID and original creation boundary, accepts no user redirect or target, and still requires fresh private creation proof. See [delivery diagnostics and recovery](TELEGRAM_NEW.md#delivery-diagnostics-and-recovery-api).

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.

### Manager registry and shared BotFather help

The following routes are relative to `/api/v1/admin` and require a first-party
human administrator with a current admin role. Responses containing management
state use `Cache-Control: no-store`. Manager tokens are write-only. The original
`telegram-new` Platform Credentials entry remains the default manager; additional
managers use their verified numeric Telegram bot identity. The registry allows
at most 100 managers, including the default.

| Method | Route | Request and result |
| --- | --- | --- |
| GET | `/telegram-managers` | List `{manager_bot_id, username, ready, legacy_default}` records. |
| POST | `/telegram-managers` | Configure `{token}` after Telegram identity verification; returns the configured manager's metadata. |
| POST | `/telegram-managers/clear` | Remove an additional manager with `{manager_bot_id}`; returns 204. Live dependencies prevent removal. Manage the default through Platform Credentials. |
| GET | `/platform-help` | List libraries with `{id, name, version, published_revision, draft, updated_at}`. |
| POST | `/platform-help` | Create `{name}`, seeded with the built-in published help. |
| PUT | `/platform-help/{id}` | Save `{version, content}` as a draft. |
| POST | `/platform-help/{id}/publish` | Publish `{version}` or republish a historical version with `{version, rollback_revision}`. Returns the updated library; rollback appends a revision. |
| GET | `/platform-help/{id}/history` | Read up to 50 revisions, newest first; `?before={revision}` pages backward. Each entry includes `{revision, content, published_at, published_by}`. |
| GET | `/platform-bots/{id}/help-library` | Read `{profile_id, library_id, version}`; an unassigned profile uses the shared default library. |
| PUT | `/platform-bots/{id}/help-library` | Assign `{generation, version, library_id}` using the current profile generation and assignment version. |

`content` contains `articles: [{id, title, body, tags}]` and
`use_cases: [{id, title, description, example_prompts}]`. IDs are unique lowercase
hyphenated slugs across both lists. Libraries allow 1–30 articles, up to 20 use
cases and 16 KiB of serialized content. Invalid content returns 400; stale edit,
publication or assignment versions return 409. Saving a draft leaves published
content available. Publishing affects new turns on every assigned bot, while
an in-flight turn retains its first selected library revision.

Additional manager webhooks use
`POST /api/v1/webhooks/channel/telegram-new/manager/{id}` and verify the
selected manager's own webhook secret. The existing default-manager webhook is
retained. After browser approval, the pairing response provides a `confirmation_command`;
the page also constructs a Telegram return link for the selected manager.
Polling and `/check` report
status; completion still requires proof from the originating Telegram account.

---

## 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.

#### Automation coordinator completion

When coordinator completion is enabled and every serving replica advertises
`automation:coordinator-completion-v2`, newly admitted assistant runs track
specialist assignments and group handoffs through the coordinator's final reply.
Existing runs retain their admission protocol. See [schedules and rollout](NYXBOT_SCHEDULES.md)
for the default-off configuration, bounds and downgrade procedure.

Run-history responses from `GET /api/v1/triggers/{id}/runs` add
`coordinator_deadline` (RFC 3339), `wait_kind` and `can_cancel` for enrolled runs;
legacy runs omit these fields. `wait_kind: "coordinator"` means delegated work is
pending. The hard deadline terminates the run with `reason: "coordinator_timeout"`.

`POST /api/v1/triggers/{id}/runs/{run_id}/cancel` returns the owner's updated run
metadata with HTTP 200. It cancels an enrolled run and fences its delegated work;
already completed external actions remain completed. This route requires a
first-party human session and rejects API keys, delegated tokens, service-account
tokens and relay tokens. An unrelated waiting run survives ordinary chat Stop.

`GET /api/v1/admin/automation-continuations/readiness` requires admin or operator
access and returns `configured`, fleet `readiness`, `rollback_safe` and
`drain_blockers`. It reads bounded, indexed metadata only; it neither changes
rollout state nor returns instructions, transcripts, result bodies or credentials.

#### 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.


## Owner NyxBot invocations

These endpoints let a first-party owner account session or access token drive
the existing NyxBot engine. Developer OAuth clients, delegated tokens, service
accounts, relay tokens, and API keys (including Agent Key login) are rejected.
The local `nyxid nyxbot` commands use this resource; no MCP setup is required.

| Method and path | Behavior |
| --- | --- |
| `POST /api/v1/assistant/nyxagent/invocations` | Admit owner work atomically, or return its existing receipt |
| `GET /api/v1/assistant/nyxagent/invocations/{invocation_id}` | Read durable status, bounded replies, and required actions |
| `POST /api/v1/assistant/nyxagent/invocations/{invocation_id}/cancel` | Fence that invocation and its associated work, then request cancellation |

Create requires `idempotency_key` (a canonical UUID v4) and `text`. Optional
`conversation_id` resumes a private owner thread; optional `agent_id` and
`model` select a new thread and cannot accompany `conversation_id`. Unknown
fields are rejected. New admissions return HTTP 202, identical retries HTTP
200, and changed requests with the same owner/key HTTP 409. The public
invocation ID is that owner-scoped idempotency key.

Existing grants, billing, and owner confirmations apply. A local wait timeout
does not cancel work. Cancellation cannot undo effects already dispatched to
an external service; unconfirmed external stops remain `requires_review`.

Admission defaults off behind `assistant:owner-invocations`. Upgrade every
replica before enabling it. Inspection and cancellation remain available with
admission off while the engine is enabled. After the first admission, recovery
is forward-fix-only because older binaries do not enforce the invocation
credential and cancellation fences.

See the [owner CLI/API reference](chat/09-owner-cli-api.md) for the full
request/response schema, lifecycle, limits, and rollout contract, and the
[CLI reference](site/cli/reference/nyxbot.md) for terminal examples.

NyxBot channel link and chat override targets follow the organization-agent
boundary and recovery contract in [ORG_AGENTS.md](ORG_AGENTS.md).

## NyxBot CMA Sandbox management scope

`GET /api/v1/assistant/nyxagent/sandboxes` lists only Sandboxes with a
server-written creation record in this NyxID database. It requires a first-party
human owner and the CMA feature flag. The response includes `sandboxes`,
`next_cursor`, `occupied`, `limit`, `conflict`, and `inventory_complete`.
`occupied` counts the owner's allocation across all pages, chats, roles, keys,
and connection aliases; `limit` is `1`. Creating or logging into a Sandbox
directly in CMA does not make it a NyxID-created resource.

The same scope applies to Sandbox detail, label, lifecycle and event routes,
Agent parent bindings, `nyxid__list_cma_resources`, and cached assistant context.
External `discovered`, `claimed`, or `conflict` references are hidden and cannot
be used to manage an external Sandbox. There are no Sandbox `claim` or
`unregistered` management endpoints. Raw CMA catalog proxy reads retain CMA's
own response and may list other resources in the upstream account.

The Agent summaries in `nyxid__list_cma_resources` and the cached CMA context
include nullable `last_known_response_id`, taken from an existing observed
submission. This lets another NyxBot chat locate that work without copying the
source chat's transcript. It is a historical lookup hint, not the current task
or permission to control it. Read the live Response and verify its conversation,
then check the controls' `target_active` and revision before proposing a control.
An absent or completed hint must not be replaced with a guessed Response ID.

Pending, unknown, paused, failed-but-not-cleaned-up and retiring creations keep
the NyxID allocation. An exact idempotent retry resumes the original intent;
confirmed retirement or confirmation that no resource was created releases it.
NyxID enforces this allocation locally. CMA retains its independent upstream
limits; origin-aware CMA quota support is not required.

`GET /api/v1/assistant/nyxagent/cma-agents/{id}/transcript` preserves CMA's
authoritative `turns` alongside the legacy deduplicated `messages` list. Each
turn contains `turn_sequence`, nullable `started_at`, `status`, and `messages`.
Statuses are `active`, `completed`, `failed`, `interrupted`, or `unknown` for an
absent/unrecognized upstream outcome. A retried turn may reuse the same admitted
owner message; it remains present in each turn but only once in the flat list.
Duplicate or non-increasing turn identities and conflicting message identities
are rejected. There are at most 10,000 turns and message occurrences per read.

The cloud assistant detail page presents one Conversation view beside Desktop.
An exact response link is checked against the requested Agent and resolved only
through a consistent V2 `turn_started.response_binding`; message text or the
Agent's latest status cannot select a turn. Missing bindings remain explicitly
unresolved. Execution details use the authoritative turn boundaries and exclude
conflicting explicit bindings. Terminal transcript outcomes remain terminal;
an active turn can show its own observed approval wait. The Agent-level status
is displayed separately. Main-chat cards retain their existing contract.

For the current CMA desktop creation flow, `create_agent` must explicitly send
`desktop=true` and an `initial_message` containing the user's exact first task.
CMA retains that task during preparation and executes it afterward. The retained
`machine_included` option alone does not enable this flow. Normal setup requests
may still omit both new fields. Recovery preserves the exact original body
bytes and Idempotency-Key, including JSON field order and whitespace.

The final dispatch boundary recognizes only the exact missing-first-message
desktop refusal and typed `desktop_unsupported` response from the Agent lifecycle
creation endpoint as additional authoritative no-resource results. It releases
the matching creation and allocation transactionally, provided no operation or
resource receipt is already recorded. Other validation errors, 403 permission
failures, transport failures, empty inventories and failed lifecycle observations
do not prove that an earlier submission created nothing and retain the allocation.

CMA provisioning observations preserve the known `sandbox_ready` phase as
preparation progress. A `running` operation in that phase remains Starting
(Preparing sandbox in the card); the phase name alone does not prove that the
Agent or Sandbox is ready. `desktop_preparation` is likewise preparation progress,
displayed as Preparing desktop without treating it as a ready environment or an
observed desktop frame.

Sandbox responses include a `capacity` object with `cpu_millis`, `memory_mib`,
and nullable `source`. `profile_revision` means capacity read from the exact
pinned Profile revision; `runtime_allocation` means a verified owner allocation
read from CMA's Sandbox usage API. NyxID saves the first complete positive pair
and its source as the resource specification for that creation identity. Once
saved, ordinary observations read only lifecycle/ownership and skip additional
profile or allocation requests. Pause, revive, retirement and unavailable
observations preserve the saved capacity; clients display it independently of
lifecycle state. This is not live utilization or a promise that a paused resource
is currently running. Capacity is looked up only while no verified pair is
stored; failures leave it unconfirmed without making the inventory unavailable.
Legacy numbers without a source do not establish verified capacity. Each initial
enrichment call has a two-second budget and at most eight reads; this is not an
overall management-request timeout. A new Sandbox creation has its own capacity;
resource resizing and automatic capacity refresh are outside this contract.

The native `nyxid__cma_save_attachment` tool accepts a `path` relative to CMA's
filesystem API root, `/home/`. A successful receipt returns `path`,
`absolute_path`, `size`, and `sha256`; subsequent Agent commands should use
`absolute_path` because an Agent's working directory can be its own Worktree.
For example, `acceptance/input.txt` returns `/home/acceptance/input.txt`.
An identical existing file is an idempotent success; different content is not
overwritten. Attachment access remains restricted to the originating
conversation and its current owner, grant, turn, and created Sandbox binding.

## Assistant voice and dictation

The [voice contract](chat/11-voice.md) specifies the existing call lifecycle,
options, controls, captions and billing. Platform audio in a private specialist
thread does not require granting OpenAI as a tool. The live conversation, agent
and key binding, platform ACL, operation restrictions and billing admission still
apply. BYOK retains the exact selected connection's ownership and grant checks.

`GET /api/v1/assistant/nyxagent/voice/options` also accepts an omitted
`conversation_id` for editing account voice settings before a conversation exists.
This first-party human, feature-gated mode returns caller-visible catalog metadata
and personal connections without creating a thread, reserving funds, or authorizing
a call. Supplying `conversation_id` retains the live thread and source checks above;
call startup always reauthorizes the selected connection against its actual thread.

Devices use a published Bot Voice service with their own ordinary Agent Key.
The human owner publishes a connection through
`GET, PUT /api/v1/assistant/nyxagent/agents/{id}/voice-service` and grants its
exact `UserService.id` through existing Key service scope. The service URL is
`{BASE_URL}/api/v1/proxy/nyxbot-voice/{service_id}`; it exposes `/voice/options`,
`/voice/sessions`, session status/control/stream and bounded announcements.
Each connection fixes one Bot, and each call binds the actual login child
credential. Existing browser routes remain first-party human only.
See [Agent Key voice service](chat/12-agent-key-voice.md) for the operation table,
independent Bot/device grants and lifecycle. Ending audio leaves accepted Bot
work running; explicit Stop cancels it.

Dictation adds two first-party human browser routes:

| Route | Contract |
| --- | --- |
| `GET /api/v1/assistant/nyxagent/dictation/options?conversation_id={id}` | Read-only eligibility and price discovery. Returns `options`, `transcription_model` (`gpt-live-transcribe`) and `max_seconds` (`120`). Options use the voice option schema with platform OpenAI sources. No funds are reserved by discovery. |
| `GET /api/v1/assistant/nyxagent/conversations/{id}/dictation` | Same-origin WebSocket upgrade authenticated by a live browser session. Requires enabled voice features and a private authorized conversation; delegated credentials cannot execute it. |

Within five seconds of upgrading, send one JSON message containing
`client_request_id` and `preferences` (the existing voice preferences schema).
The server selects only platform OpenAI transcription. After the server's `ready`
event, send binary PCM16 mono audio at 24 kHz, at most 4096 bytes per message, or
the exact text message `{"type":"stop"}`. Capture is bounded to 120 seconds.
Provider commands, keys, tools and destination overrides are not accepted.

Server events are `ready` (`session_id`, `model`), `delta` and `completed`
(`item_id`, `order`, `text`; completion also includes `confirmed_seconds`),
`stopped` (`confirmed`), and `error` (the standard sanitized `error` envelope).
The browser reviews the resulting text before inserting it into a draft; the
transport never submits a chat message. Closing capture releases the microphone
immediately while the server drains forwarded audio within a bounded deadline
and settles provider-confirmed input duration. See the
[transport and accounting contract](chat/11-voice.md#bounded-transcription-transport-and-accounting)
for limits, exact duration handling and recovery.

## Generated Sandbox attachments

The default-off `assistant:generated-artifacts` flag enables private generated
files on owner Web conversations. History adds optional attachment metadata and
`artifact_delivery` state only while enabled. Existing attachment values remain
unchanged. See [generated files](chat/10-uploads.md#generated-sandbox-files) for
limits, retention, rollout order and recovery semantics.

| Endpoint | Contract |
| --- | --- |
| `GET /api/v1/assistant/nyxagent/conversations/{id}/attachments/{attachment_id}` | Existing authenticated owner attachment route. Generated rows additionally bind conversation keys to their own conversation and return a complete HTTP 200 response with safe download/preview headers; Range is ignored. Retained owner reads remain available while the flag is off, until live expiry. |
| `POST /api/v1/assistant/nyxagent/conversations/{id}/messages/{message_id}/artifact-delivery` | First-party human owner only, enabled feature and no active turn. Requires an empty body. Recovers saved bytes onto the original associated reply without another Sandbox execution; returns `{ "status": "materialized" }`. Disabled routes return 404; active turns return 409; expired attachments return 410. |

Eligible owner NyxAgent chat keys also receive `nyx__artifact_delivery`, accepting
an empty object. The server freezes its original-reply target and preflights
recoverability before auditing or requesting an owner confirmation. Disabled or
ineligible callers retain the ordinary unknown-tool response.

## Assistant skill review and image input

`GET /api/v1/assistant/nyxagent/conversations/{id}` accepts an optional `card`
UUID alongside the existing `limit` and `before_seq` pagination parameters.
It includes that acknowledgement in the history response even when the card is
outside the normal recent-card window. The caller must have access to the
conversation, and the selected card must belong to that same authorized
conversation. Omitting `card` preserves the existing history request behavior.

Authored skill tool results and proposal listings include `review_url`, an
absolute link to `/assistant?c={conversation_id}&card={acknowledgement_id}`.
Proposal listings also expose the associated card state. Group pending-action
responses carry an optional review link so the reviewing owner can open the
complete file review. Authored review links replace chat confirmation phrases:
typed channel replies cannot approve publication. The link identifies a review
surface and grants no additional authority. See [Agent learning](AGENT_LEARNING.md)
for the full draft, approval and explicit expired-card renewal contracts.

`GET /api/v1/assistant-attachments/{id}/content` accepts a live conversation
Agent Key for model image input. Alongside user-uploaded image selection, it can
serve retained tool-returned raster images from that key's active turn. It
rechecks conversation, owner, key, Stop, organization access and retention;
an unrelated key or turn cannot retrieve the pixels. Capability negotiation
controls optional model image rounds, so older NyxAgent deployments retain
text-only behavior. See [Uploads](chat/10-uploads.md) for content limits and
fallback behavior.

## Tools

See [TOOLS.md](TOOLS.md) for the model, publication boundary, roles and CLI walkthrough.

`GET /api/v1/tools` and `GET /api/v1/tools/{slug}` return published, credential-ready offerings under the caller's live platform-key ACL. Fields include supplier, topics, import source, access lanes, exact decimal pricing, limits, and published operation classifications. `GET /api/v1/tools/topics` returns the controlled vocabulary. Metadata reads support delegated `account:read`; catalog-editor service accounts use `/services` routes.

`POST /api/v1/services/{id}/endpoints/{endpoint_id}/publication` accepts `{ "state": "published" }`. The bulk `/api/v1/services/{id}/publication` accepts `{ "state": "paused", "endpoint_names": ["search"] }` (1–200 distinct names). States are draft, validated, published and paused. Only published operations execute; blocked tool operations return HTTP 404 / code 12700, including the HTTP and WS proxy. MCP calls return `isError` with the same code.

Tool service writes and publication require platform admin authority in Phase 1. `/keys` hides platform tool bindings and retains BYOK bindings with `offering_kind`; human `/catalog` excludes tools by default (`?offering_kind=tool` or `include_all=true` opts in). MCP discovery includes tools under unchanged `{service_slug}__{endpoint.name}` identities. Runtime overlay storage and editor scopes are Phase 2.

`POST /api/v1/services` supports `twin_of_service_id` (catalog UUID or slug) with a required new `slug`. It clones allowed transport/spec/discovery metadata and all endpoint rows into an internal, provider-less `tool` with no credential, default enabled/public platform-key configuration, and `catalog_twin` provenance. Copied endpoints receive new UUIDs, generation 1 and inactive draft state in the catalog create transaction. Request metadata overrides copied fields. Source credentials and provider links are never copied; configure the credential after creation. Eligible existing rows can instead flip through `PUT /services/{id}` with `offering_kind=tool`, retaining existing published operations. Manager twins use sanitized inheritance, restricted empty audience and live creator/role fences. See [Tools](TOOLS.md) for supported `admin tools add|apply|validate|icon` workflows. No tool rows are seeded.

Tools updates distinguish omission from JSON `null` for `supplier` and `import_source`: omit to retain, null to clear. `GET /api/v1/keys?include_tool_bindings=true` includes otherwise-hidden platform Tool bindings with the existing KeyResponse shape; default listing still hides them and includes BYOK rows. Owner, membership, restricted API-key and delegated read semantics are unchanged. Tools `limits` is null when `PLATFORM_SERVICE_RATE_LIMIT_PER_SECOND=0`, otherwise `{ rate_limit_per_second, burst }`.

CLI catalog creation requires `--endpoint-url` or `--twin-of` (otherwise the local error is `Catalog creation requires --endpoint-url or --twin-of`). Catalog updates support `--clear-supplier`, conflicting with `--supplier`. Tools table output formats prices as `Free` or `<credits> credits / <metric>`, limits as `<n>/s, burst <b>` or `none`, and topics as a comma-separated list. `tools show` prints rows for each operation (name, method, path, risk, data scope, cost class). JSON output remains the raw response.

## Oracle pool lifecycle (unreleased)

Oracle is an authenticated asynchronous browser-worker task relay. Pool management
accepts the same JWT/general API-key callers as other Oracle consumer operations;
shared worker and installation tokens do not authorize management. The pool owner
is the existing person/org `user_id`; platform visibility grants discovery/use,
not ownership. The first tagged release containing issues #1527/#1542 adds:

| Method and path | Request | Success / conflicts |
|---|---|---|
| `POST /api/v1/oracle/pools/{id_or_slug}/transfer` | `owner_user_id` UUID, optional `rotate_worker_token` (default false), optional `visibility:"private"` for org-visible → person | 200 `{pool, worker_token?}`, no-store; source/destination manager ACL, active own-person or active managed org, ten-pool destination limit |
| `DELETE /api/v1/oracle/pools/{id_or_slug}` | No body | 200 `{id,slug,status:"deleted",cleanup:"asynchronous",deleted_at}`, identical on authorized retry; 409 `oracle_pool_active_work` for queued/dispatched tasks or queued/delivered commands; 403 forbidden, 404 unknown |

Transfer preserves pool identity/settings/history and the shared token by default.
Owner changes require fresh installation credentials. Deletion reserves the slug,
hides discovery and invalidates all workers at commit. Durable bounded cleanup
then closes idle sessions and removes worker rows and encrypted login material;
`cleanup:"asynchronous"` acknowledges this policy, not physical completion.
Terminal task TTLs and readable history remain. Idle online
workers do not block deletion. Settle active work before deletion. All replicas and
old in-flight requests must be upgraded/drained before lifecycle operations are
used. See [Oracle Relay](ORACLE_RELAY.md#pool-ownership-and-deletion-unreleased-1527-1542)
for retention, retry, concurrency, token and deployment contracts and CLI examples.

DELETE also settles deadline-expired worker commands from any generation in at
most sixteen separately committed batches of 256 IDs per request. HTTP 409 /
11017 can therefore mean that bounded expiry progress was made and more remains;
retry DELETE. Unexpired work still blocks deletion. Authorization is checked for
every batch, and an interruption or later conflict preserves committed expiry.
Already-deleted pools skip expiry and return their stable acknowledgement.
## Complete channel replies

`POST /api/v1/channel-relay/reply` and `/thread-reply` accept one complete
logical text reply in the existing request shape. NyxID splits it for the
platform, preserves order and the bound destination, and consumes a reply
token once for the entire request. HTTP 200 means every part has a valid
platform acceptance receipt and persisted delivery metadata; the existing
`message_id` and `platform_message_id` identify the last part. Partial or
uncertain sends return an error and must not be automatically replayed.

Text-only requests are limited to 2 MiB of serialized JSON before token
consumption. Plans exceeding 64 platform parts are rejected before sending.
Rich content, media, edits and proactive sends retain their separate contracts.
See [Complete IM replies](CHANNEL_COMPLETE_REPLIES.md) for platform bounds,
metadata retention, ingress configuration and CMAEG deadline coordination.

## Channel media delivery substitutions

`POST /api/v1/channel-relay/reply`, `/thread-reply` and `/send` accept the existing
media request shape and may add `delivered_as` to a successful response. For
Telegram and telegram-new, a narrowly classified photo-specific 400 refusal
can send the same image once as a document under the
[relay fallback rules](CHANNEL_BOT_RELAY.md#image-outcomes-and-telegram-document-fallback).
A response with `"delivered_as": ["file"]` reports this actual transport kind,
and the outbound message's `content_type` is `file`. The reply anchor, topic and
caption are preserved. Other adapters can omit this field.

## NyxBot exact service selection and consent

An authenticated first-party human owner may prefix a new NyxAgent message with
`/service <connection UUID or unambiguous connection slug>` followed by a newline
and the request. The composer offers the same next-message choice. The selector
lasts one admitted turn and chooses identity, not permission. API keys (including
conversation, delegated and service-account keys), guests and webhook inputs
cannot install human selection. Ordinary new turns clear it. An approved-card
continuation inherits only that card's exact target and operation; expired,
denied or consumed cards install no selection.

Assistant raw proxy/LLM/SSH exec retries accept
`X-NyxID-Acknowledgement-Id`; MCP service and native tools accept the existing
`acknowledgement_id`. Native Oracle submit, attach and extract request bodies add
optional `acknowledgement_id: string`. NyxID consumes this control metadata only
for assistant execution; ordinary endpoint clients keep their payload contract.
No acknowledgement transport metadata reaches the provider. Assistant chat keys
use exact SSH exec and bounded certificate/tunnel/terminal session admission.
For assistant calls, organization use asks in Auto and Ask every time and Full
access proceeds without a prompt. Certificate cards bind the subject public key
and principal; session cards bind the exact connection, principal/initial terminal
geometry and maximum lifetime (at most one hour). Resume the same request with
`X-NyxID-Acknowledgement-Id`. Session consent covers dynamic session traffic;
revocation, config drift or elapsed authority closes the session. Ordinary client
routing and existing personal catalog-only access are retained.

Organization-use refusals persist the existing action card and return its
`acknowledgement_id`. Full access bypasses consent while retaining preference
and authority checks. Raw stateless org model consent admits an exact model and
connection for the resumed turn; MCP/stateful actions retain exact semantic
request consent. Machine exec cards explicitly admit declared exact organization
connections for that command/job. See [execution contract](NYXBOT_SERVICE_EXECUTION.md).

## NyxBot service adapters

The default-off `nyxbot:service-adapters` flag gates adapter setup and execution.
Upgrade every API replica before enabling it. The existing
`GET /api/v1/channel-platforms` contract is unchanged. See the
[operator guide](NYXBOT_SERVICE_ADAPTERS.md) for provider setup, supported
credential modes, dynamic instructions, FAQ grants and billing requirements.

Prefix every path below with `/api/v1`. Binding management and secret/session
issuance require a first-party human account and verify ownership. Administrator
account/allocation routes additionally require the administrator role. Capability
metadata allows delegated `account:read`. List routes accept `after` and return
`next_after_id`; an absent cursor marks the final page.

| Method | Path | Result |
| --- | --- | --- |
| GET | `/channel-adapters` | Versioned executable descriptors in `adapters`, including legacy/disabled profiles. |
| GET | `/channel-adapter-bindings` | Owner's bindings, readiness and next cursor. |
| POST | `/channel-adapter-bindings` | Verify provider resources and create a binding; returns its descriptor and readiness. |
| POST | `/channel-adapter-bindings/{id}/disable` | Disable admission and start cleanup; 204. |
| POST | `/channel-adapter-bindings/{id}/verify` | Reverify and enable; returns the updated binding. |
| DELETE | `/channel-adapter-bindings/{id}` | Remove a disabled, settled binding; 204. |
| POST | `/channel-adapter-bindings/{id}/custom-llm-setup` | ElevenLabs Custom LLM URL, API key and model; secret-bearing response. |
| POST | `/channel-adapter-bindings/{id}/sessions` | Issue a distinct ElevenLabs guest session and `extra_body` authentication. |
| POST | `/channel-adapter-bindings/{id}/sessions/{sid}/end` | End an owned ElevenLabs guest session; 204. |
| GET, POST | `/admin/channel-adapter-accounts` | List or configure trusted provider accounts; POST returns 204. |
| DELETE | `/admin/channel-adapter-accounts/{id}` | Remove trust after allocations are removed; 204. |
| GET, POST | `/admin/channel-adapter-allocations` | List or allocate platform number/application resources with tariff evidence. |
| DELETE | `/admin/channel-adapter-allocations/{id}` | Revoke allocation; pending cleanup prevents premature removal. |

Binding creation accepts `adapter_id`, `contract_version: 1`, `label`, `agent_id`,
`credential` and provider-specific resource settings. `credential` is either
`{"kind":"connection","user_service_id":"..."}` or
`{"kind":"platform","catalog_service_id":"..."}`. Carrier settings include
`account_id`, `resource_id`, `phone_number`, `application_id`, `voice` and
`language`; user-owned Telnyx additionally supplies `webhook_public_key`.
ElevenLabs uses its agent ID as `application_id`. Creation verifies ownership
without placing a call or sending SMS. A binding response contains identifiers,
configuration, `enabled`, `revision`, `verified_at`, `webhook_url` and per-operation
`availability`; it never returns stored credentials.

Provider-facing routes authenticate their own protocol instead of a human login:

| Method | Path | Authentication and transport |
| --- | --- | --- |
| POST | `/webhooks/call-adapters/{id}` | Telnyx Ed25519 or Twilio signature plus bound resource proof; bounded body, XML response. |
| POST | `/webhooks/call-adapters/{id}/sms-receipts/{send}` | Signed, correlated delivery receipt; bounded body, XML response. |
| GET | `/webhooks/call-adapters/{id}/socket/{sid}` | Admitted session ticket, plus Twilio signature when applicable; WebSocket upgrade. |
| POST | `/webhooks/call-adapters/{id}/v1/chat/completions` | Custom LLM bearer and separately issued guest-session credentials; bounded JSON input and SSE output. |

Caller messages never grant owner authority. Specialist guest grants, live
binding/session authority and catalog operation policy remain mandatory at
execution. Provider retries do not automatically repeat uncertain effects.


### Credit Allocations

All routes below require authentication and retain the existing admin Credits
role boundaries. They are additive to existing `/admin/credits/grants`,
`/admin/credits/schedules` and allowance APIs; personal billing routes are unchanged.

| Route | Authority | Contract |
| --- | --- | --- |
| `GET /api/v1/admin/credits/allocations/summary` | Admin or Operator | `allocations_v1` authoring capability and exact decimal-string summary: remaining, unreserved, held, pending activation/reclaim, expired awaiting cleanup, restricted, generated time. Subsets are not additive funds. No financial writes. |
| `POST /api/v1/admin/credits/allocations` | Admin or Credits Manager Operator | Issue one-time allocation using existing recipient/scope fields plus exact decimal `amount`, optional UUID `request_id`, and optional `service_limits`. |
| `DELETE /api/v1/admin/credits/allocations/{grant_id}` | Admin or Credits Manager Operator | Reclaim only this allocation's unused funds. Held work completes; response may carry `revoke_requested_at` until final reclaim. Replays converge on the same state. |
| `POST /api/v1/admin/credits/allocations/schedules` | Admin | Create daily/weekly/monthly policy with expiry and optional limits/request UUID. Each period freezes policy; each recipient grant has fresh counters. |
| `PATCH /api/v1/admin/credits/allocations/schedules/{schedule_id}` | Admin | Sparse reviewed edits; changes apply to future periods. Pausing does not reclaim existing allocations. |

New mutations require `BILLING_ALLOCATIONS_ENABLED`; disabled deployments reject
new policy authoring. Never retry capped policies through legacy endpoints on a
missing capability. An exact read field alone is not proof of exact write support.
Legacy omitted fields remain supported; legacy immediate revoke rejects holds
when the new capability is disabled.

Creation accepts the canonical exact string `amount` without an
`amount_credits` field, for both one-time and recurring allocations. Legacy
whole-integer `amount_credits` requests remain valid. When both fields are
present, `amount` takes precedence; omitting both, or providing a nonpositive,
malformed or unrepresentable effective amount, rejects the request without
creating an allocation or schedule. Sparse recurring updates preserve an
omitted amount, and apply the same exact-field precedence when supplied.

`service_limits` entries contain `service_refs` (one or more concrete catalog IDs
or compatible slugs), exact decimal `amount`, and optional `label`. Canonical
services must be disjoint across rules and within selected eligibility. Limits
are ceilings inside a shared total, not earmarked pots; unspecified eligible
services remain unrestricted. Returned rules include exact limit/consumed/raw
reserved/additive held values and canonical members. Grant responses preserve
legacy fields and add exact `held`, `terminal_amount`, `reclaimed`, pending reclaim
and rule details. Money supports twelve fractional digits without JSON-number loss.

An actor-scoped request UUID freezes payload and recipients. Retrying the same
payload resumes safely; reusing the UUID for different settings returns conflict.
See [exact allocation accounting](BILLING_EXACT_ACCOUNTING.md#allocation-local-service-ceilings-and-reclaim)
for rollout, activation, journal and recovery guarantees.

## NyxBot gateway release review

All routes require a live platform admin. Delegated `account:read` access is denied
by the existing `/admin` route class. Responses contain captured public identity,
state, revision and versions; they omit credentials, key IDs/hashes, ciphertext and
remote response bodies. See [gateway lifecycle](CHANNEL_EVENT_GATEWAY.md#nyxbot-gateway-retirement-and-recovery).

| Method | Path | Request and response |
| --- | --- | --- |
| GET | `/api/v1/admin/nyxbot-gateway-releases` | Optional `after` UUID cursor, `limit` (default 50, capped at 100), comma-separated `states` (default `due,review_required`). Returns `{items, next_cursor}` ordered by ID. |
| POST | `/api/v1/admin/nyxbot-gateway-releases/{id}/inspect` | Returns `{captured, observation}` with captured revision and a fresh sanitized observation; does not change captured authority. |
| POST | `/api/v1/admin/nyxbot-gateway-releases/{id}/resolve` | Body `{revision, observation, action, dispatch_drained?}`. Echo the inspected observation and revision; returns 204 after a live admin check and fresh matching observation. |

Observation `status` is `missing`, `matching` (with `channel_id`, `version`),
`changed` (with optional `version`), `malformed`, `destination_changed`,
`live_reference` or `owner_unavailable`. Resolution actions are `retry_original`,
`preserve_changed`, `confirm_missing`. Only `review_required` records can be
resolved. `retry_original` accepts `matching`, or `missing` while the channel
identity is still unknown. `preserve_changed` accepts every status except
`matching` and `missing`; it settles as `preserved` without deleting anything,
records the observation status in audit metadata, and leaves `gateway_released`
false. `confirm_missing` accepts `missing`. For an uncertain create, it also
requires the 24-hour dispatch window to have elapsed and `dispatch_drained: true`;
absence alone never proves no creation. A stale revision/observation returns
conflict; an invalid action returns validation failure. Authority/storage
unavailability is retryable. No action deletes a replacement version.

### OAuth consent decisions

Browser consent forms submit a `browser_form=true` marker. Successful, denied,
and callback-error decisions return a script-free 200 interstitial that performs
a meta-refresh to the already validated callback; API and non-browser callers
retain the normal 302/JSON contract. An unauthenticated form is also completed
through the interstitial before its same-origin `/login?return_to=...` navigation.
OAuth redirect URIs are checked at both
registration and execution time. HTTP(S), loopback HTTP, and RFC 8252 private-use
native schemes (including reverse-DNS schemes with a path) are accepted;
browser execution, content, local-file, and opaque schemes are rejected with
the normal invalid-redirect error.
Registration trims surrounding whitespace and stores the trimmed exact string;
embedded tab/CR/LF are rejected. Execution requires the exact registered string
and rejects browser-normalized whitespace/control variants.

An ordinary approval preserves the live consent's existing scopes, service
allowlist, and expiry and unions the newly approved request. The standard screen does not
provide a complete editable view of the grant, so it cannot silently narrow
previous authority; use Authorized Applications to revoke or narrow access.
Reordered or duplicate selections are equal authority and are a no-op: the
consent id, revision, issuance fence, and Machine external grant remain stable.
Incremental approval with no additions has the same no-op behavior. Pure broadening
preserves the existing authority revision and does not invalidate tokens bound to it;
each token remains limited to its own scope, service, and resource claims. Narrowing,
expiry shortening, revoke, regrant, and authority-removing Machine or binding changes
create a new revision and invalidate tokens bound to the previous revision.

The new code carries only the approved request's validated scope, its service
selection and required resource services; it does not inherit the older stored
union or its allow-all flag. CAS uses an independent optional `write_version`,
compatible with old rows/readers. Signed decisions bind the revocation generation, so a request issued before
revocation fails with a conflict and requires fresh authorization; a new request
can authorize immediately. Old signed requests use a conservative timestamp
compatibility fence, including same-second revocation. Double submit before
revocation is harmless. URI
spelling is preserved exactly: tab/CR/LF anywhere and leading/trailing C0/space
are rejected rather than normalized into a match.

### Assistant hosted connection intent and discovery

`nyx__connect_service` accepts `service_id` (catalog UUID), `service_slug`, or both matching the same authorized active catalog. Mismatch, missing and inaccessible catalogs are not-found-shaped; visibility and caller scope precede actionable results. When an eligible assistant chat key connects the owner's own credential (`use_platform_key` false or omitted on a credential-requiring catalog), it receives `pending_connection` with `connect_url`, `connect_link_id`, `catalog_service_id`, `service_slug` and expiry, and the link carries personal intent. Platform-key (`use_platform_key=true`) and credential-free connects keep their existing one-step behavior. Specialist keys remain denied with safe catalog guidance to NyxBot/Plugins and a separate grant step. Existing non-assistant credential/provisioning behavior is retained.

Plugins **Connect** creates an ordinary `POST /api/v1/connect-links` with `service_slug`, leaving the credential choice to the hosted page. **Connect your own** (and the org card's action) sends `service_slug`, `use_platform_key:false`, `assistant_personal:true` under a first-party human session. After readiness activation of `assistant:hosted-connect-intent-v1`, assistant personal-intent links (MCP and Connect your own) store `assistant_intent_locked:true`. Preview exposes this default-false field. Completion and pinned-flow resume reject a differing explicit `use_platform_key`; stored intent controls. Legacy/non-assistant links remain overrideable. Link completion never grants a specialist automatically.

MCP search/list and `nyxid__list_my_services` retain existing fields and add `connection` facts: visible `catalog_service_id`/`catalog_service_slug`, `owner_type` (`person`/`organization`), `relation` (`self`/`shared_person`/`organization`), `organization_name` and `account:{status:"unknown"}`. Ownership describes the actual owner UserType, not whether owner differs from actor. `granted` means scope access; covered org execution still needs instruction in Full access. Org action acknowledgements include `confirmation.reason:"org_connection"` and a `connect_own` object: supported offers contain safe catalog ID/slug; unsupported offers include an explicit reason and guidance. The UI creates the hosted personal link only on owner click.

### Multi-person assistant groups

The existing `/api/v1/assistant/nyxagent/groups` routes dispatch explicit
collaboration groups separately from legacy personal crews and org groups.
Create one with `collaboration: true`, `name`, and 1–8 `member_agent_ids` (specialists
only). Creation and new work require the default-off `assistant:shared-agents`
flag and full-fleet `assistant:collaboration-groups-v1` readiness. Human
`GET /api/v1/assistant/nyxagent/collaboration` returns `{ "available": boolean }`.
Legacy groups are never converted. Non-participants receive a not-found-shaped
denial, and hidden execution IDs/keys are never returned.

Under that prefix, `POST /groups/{id}/membership` accepts `expected_revision` and
a tagged `action`: `invite`, `cancel_invite`, `quick_add`, `remove`, `leave`,
`delete`, `propose_transfer`, `accept_transfer`, `add_agent`, `propose_agent`,
`accept_agent`, `remove_agent`, `guest_access`, `rename`, or `lead`. Stale
membership revisions return 409. Transfer proposal/acceptance is human-only.
Dedicated invite, participant, leave and guest-access aliases are documented in
[the complete contract](chat/12-shared-agents-and-groups.md#10-rest-nyxbot-tools-and-mcp-parity).

Invites return their seven-day single-use token once. The invite action and
`POST /groups/{id}/invites` accept optional `intended_user_id` to bind the token
to an existing person; omit it for a bearer link. Human
`POST /group-invites/preview` accepts `{ "token": "..." }`; acceptance adds
`"history_disclosed": true` and requires a signed-in person. New participants
see all retained history, and quick-add requires the same disclosure. A creator
must complete an accepted management transfer before leaving, or delete the
group. No invite message is sent automatically.

Messages accept exact `recipient_agent_ids` and attachment IDs. Every reply and
handoff runs for the original requester: owner/org/shared authority first, then
owner-opted-in guests, otherwise a fixed refusal without model work. Shared
usage bills the requester; org BYOK/platform and owner/guest billing retain their
existing rules. `POST /groups/{id}/requests/{request_id}/cancel` stops only that
requester's work. `POST /groups/{id}/decisions/{decision_id}` accepts `kind`
(`action`/`consent`) and `decision` (`allow`/`deny` or `once`/`always`/`skip`).
Service approvals use the existing approval decision endpoint. Exact cards and
account labels are visible only to their requester; other participants see
waiting status. Group membership changes invalidate those decisions.

A personal specialist owner may read `GET /agents/{id}/group-access` to manage
that agent's guest settings by group ID and policy/membership revision, even
without joining. It reveals no group names, participants or transcript. Enabling
guests covers current and future unauthorized participants and bills the owner;
NyxBot always requires an owner card, including in Full access.

Native tools and MCP expose `create_collaboration_group`,
`list_collaboration_groups`, `manage_collaboration_group`, and
`post_to_collaboration_group` through the same service boundaries. Public REST
writes remain first-party human only. Flag-off preserves authorized retained
history, cancellation, departure and deletion; binary rollback requires the
archive/drain procedure in the design.


## CMA Sandbox billing producer API

The routes below require a verified service-account JWT from the single
configured CMA producer and issued/live `billing:sandbox:write` scope. They do
not accept user sessions, user access tokens, API keys, delegated or relay
credentials. New admission defaults to disabled. Full request/response examples,
units, retry semantics and rollout requirements are in [CMA billing](CMA_BILLING.md).

| Method | Path | Purpose |
| --- | --- | --- |
| POST | `/api/v1/billing/sandboxes/quotes` | Quote the existing catalog service prices for an owner and full Sandbox allocation. |
| POST | `/api/v1/billing/sandboxes/windows` | Atomically reserve at most 300 seconds across all applicable resource metrics. |
| GET | `/api/v1/billing/sandboxes/cursors/{sandbox_id}` | Recover the durable ordered allocation-evidence checkpoint. |
| GET | `/api/v1/billing/sandboxes/receipts/{request_id}` | Recover an already committed producer request, including during an admission/provider outage. |
| POST | `/api/v1/billing/sandboxes/windows/{window_id}/evidence` | Finalize retained allocation intervals and queue the existing settlement/reconciliation path. |

Bodies are bounded to 512 KiB; evidence is bounded to 1,024 intervals. Client
price/amount fields and other unknown fields are rejected. A reused request ID
with different input, changed final evidence, or changed retained ledger
revision is a conflict. Evidence acceptance is distinct from provider emission.

CMA service-owned producer settings: `GET` (admin/operator) and `PUT` (platform
admin only) at `/api/v1/admin/billing/services/{id}/sandbox`. `{id}` must be the
unique active catalog service with slug `cma`. GET returns `service_id`,
`authorized_producer_service_account_id` (null when unset), and `revision` (0
before configuration). PUT requires both `expected_revision` and
`authorized_producer_service_account_id` (a canonical UUID v4 or explicit null).
Stale revisions and changes with unreported funded windows return 409. Only an
active General-purpose account with `billing:sandbox:write` can be selected;
saving protects its credential management and atomically appends a chained audit.
No setting means no authorized producer. These settings do not enable admission
or alter prices; `experimental:cma-sandbox-billing` controls admission rollout.

CMA runtime price configuration: `GET /api/v1/admin/billing/cma-rate-cards`
(admin/operator) and `POST /api/v1/admin/billing/cma-rate-cards` (admin-only)
list and publish immutable effective-dated resource prices. See
[CMA billing](CMA_BILLING.md#enablement-and-runtime-rate-configuration) for
exact decimal payloads, validation, audit and activation semantics.