Listeners and authentication
Listeners
Section titled “Listeners”| 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 |
Tokens and keys
Section titled “Tokens and keys”| 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 |
What each endpoint needs
Section titled “What each endpoint needs”| 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.
Main address
Section titled “Main address”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.
Managed address
Section titled “Managed address”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, including0.0.0.0, needs[server] managed_tls_certandmanaged_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, gets401, withWWW-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-Projector a header that carries Prism’s own dispatch metadata (X-Prism-Idempotencyand its companions,X-Prism-Managed-Request-Id,X-Prism-Managed-Task-Key,X-Prism-Managed-Policy-Digest) get403 forbidden; provider account selection stays on the Prism side. Anthropic’santhropic-versionandanthropic-betaheaders are passed on, so Claude Code and the Anthropic SDKs work on the managed address. A version later than2023-06-01, such as2026-10-21, goes only to the Claude API (api.anthropic.com); other Anthropic-compatible providers get2023-06-01. - The managed address does not serve the Ollama API, discovery, status, cost or control endpoints.
Requests with a Prism key
Section titled “Requests with a Prism key”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 |
Console
Section titled “Console”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.
Control listener
Section titled “Control listener”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.