Skip to content

Listeners and authentication

Listener Setting Default Serves
Main [server] host, port 127.0.0.1:18000, always on All model endpoints and dialects (including Ollama), discovery, status, cost, metrics, control
Console [console] bind 127.0.0.1:18081, on The web console and its API
Managed [server] managed_bind off Model endpoints for clients with an issued key
Control [server] control_bind off Control API and discovery on a loopback address
Metrics [metrics] bind off /metrics and /health; /metrics then leaves the main listener
Name Where it comes from Used for
Owner token PRISM_ADMIN_TOKEN if set; otherwise generated on first start into <storage.dir>/console-token (mode 0600). prism console prints it Console sign-in, control API, status and metrics when protected, traces
Read token PRISM_READ_TOKEN (optional) Status, cost and metrics only
Managed key Issued in the console (Configuration → API keys → Add API key); prism_it_..., shown once, expires after 90 days by default Model requests on the managed address
Endpoints Main Managed Control Console
Model endpoints (/v1/*, /v1beta/*, root aliases) No key Managed key not served not served
Ollama API (/api/*, /) No key not served not served not served
/v1/messages/count_tokens No key always 404 not served not served
/health No key not served No key No key
/.well-known/prism.json, /prism/agent-context No key not served No key not served
/.well-known/oauth-authorization-server No key not served not served not served
/oauth/device_authorization No key not served not served not served
/oauth/token No key not served not served not served
/prism/clients/omp.ts (the omp extension) No key not served not served not served
/prism/models, /prism/session/last-served No key not served not served not served
/prism/capabilities, /prism/skills/* No key not served No key No key
/prism/status Owner or read token, if either is set not served same as main not served
/prism/cost Owner or read token, if either is set not served not served not served
/prism/routing/arms Owner or read token, if either is set not served same as main not served
/metrics Owner or read token, if either is set (only without [metrics] bind) not served not served not served
/prism/control Loopback + owner token not served Loopback + owner token Owner token (X-Prism-Admin-Token only)
/prism/funding/clear, /prism/auth/clear, /prism/health/recheck Loopback + owner token not served Loopback + owner token not served
/prism/traces/{id} Loopback + X-Prism-Admin-Token not served same as main not served

“Owner or read token, if either is set”: with neither PRISM_ADMIN_TOKEN nor PRISM_READ_TOKEN set these endpoints are open. Otherwise send X-Prism-Admin-Token with the owner token, or the read token as X-Prism-Read-Token or Authorization: Bearer. A wrong token gets 401 unauthorized. The read token never opens the control API.

“Loopback”: the request must come from 127.0.0.1 or ::1; other addresses get 403. The control API with no owner token configured rejects every request.

The separate metrics listener has no authentication; limit who can reach its address.

/.well-known/oauth-authorization-server, /oauth/device_authorization and /oauth/token let an app ask a person for a Prism key (the OAuth device grant). They take no key because the app does not have one yet, and they are on the main address only; the managed address answers 401 for them like for any request without a key. Nothing is issued until a person signed in to the Prism console allows the request, and the result is a Prism key of that person. They answer 404 when Prism cannot issue keys, or when the console is turned off or did not start. See Sign in from an app.

The main address does not check a key. Anyone who can reach it can send model requests through your provider accounts. Keep [server] host = "127.0.0.1" unless the network in front of it is yours. Browsers on other origins are refused (403) unless their origin is in [server] cors_allowed_origins. A browser request that carries a Prism key (prism_it_…) is served from any origin on every address: the key is the credential, as with provider APIs. This is how browser extensions and Office add-ins connect.

A model request that carries a Prism key is checked on the main address as on the managed one: see Requests with a Prism key.

Turn it on with [server] managed_bind, for example 127.0.0.1:18002.

  • Plain HTTP is accepted on a loopback or tailnet (100.64.0.0/10) address. Any other address, including 0.0.0.0, needs [server] managed_tls_cert and managed_tls_key; without them Prism refuses to load the configuration.
  • Every request, including requests to unknown paths, needs a Prism key (prism_it_...). Prism reads it from the same places as on the main address; see Requests with a Prism key. A request without a key, or with a key that is unknown, revoked or expired, gets 401, with WWW-Authenticate: Bearer.
  • The key’s policy limits endpoints, models, providers, spend, latency and concurrency. A request outside it gets 403 forbidden. Anthropic Messages and Gemini requests are checked as /v1/chat/completions.
  • Requests that carry OpenAI-Organization, OpenAI-Project or a header that carries Prism’s own dispatch metadata (X-Prism-Idempotency and its companions, X-Prism-Managed-Request-Id, X-Prism-Managed-Task-Key, X-Prism-Managed-Policy-Digest) get 403 forbidden; provider account selection stays on the Prism side. Anthropic’s anthropic-version and anthropic-beta headers are passed on, so Claude Code and the Anthropic SDKs work on the managed address. A version later than 2023-06-01, such as 2026-10-21, goes only to the Claude API (api.anthropic.com); other Anthropic-compatible providers get 2023-06-01.
  • The managed address does not serve the Ollama API, discovery, status, cost or control endpoints.

A model request that carries a Prism key (prism_it_…) is checked the same way on the main and on the managed address.

Where the key goes. Prism reads the key from Authorization: Bearer, x-api-key, x-goog-api-key, the key query parameter, or a /k/prism_it_… prefix of the base address; see Connect clients. Two different Prism keys in one request get 401. So does a credential in another place: Proxy-Authorization, or a query parameter that names a credential or a signed address, such as access_token, api_key, token or signature. The managed address also refuses a request that carries a cookie.

Query parameters. Besides key, the request may carry only the query parameters in this table. Any other query parameter gets 401, also when the key is valid.

Request Accepted What Prism does with them
POST /v1/messages, POST /v1/messages/count_tokens beta Ignored. Claude Code and the Anthropic SDKs send ?beta=true. count_tokens with a key answers 404, with or without the parameter
GET /v1/models, GET /models beta, limit, after_id, before_id Ignored: the answer is always the whole list. Claude Code sends ?limit=1000; the Anthropic SDKs send the others when they page through the list
POST /v1beta/models/{model}:{method} alt Chooses the framing of a streamGenerateContent answer: alt=sse for server-sent events, otherwise one JSON array. It does not start a stream; the method does
GET /v1/files, GET /v1/batches after, limit, order, purpose Sent on to the provider

The console listens on [console] bind (127.0.0.1:18081). Plain HTTP is accepted on loopback; any other address needs [console] tls_cert and tls_key, or allow_plaintext = true on a network whose transport you trust. See Open the console from another machine.

When [server] host is not loopback, requests from the Prism machine to it do not count as loopback, and the control API refuses them. [server] control_bind = "127.0.0.1:18001" starts a loopback-only listener for the control API, discovery and status. A non-loopback control_bind stops Prism at startup.