Sign in from an app
An app can ask for a Prism key instead of having one pasted into its settings. The app shows a link and a short code. A person who is signed in to the Prism console allows the request, and the app receives a key of that person. Prism implements this as the OAuth 2.0 device grant (RFC 8628).
The app needs to reach the main address. The person needs a browser that reaches the Prism console.
Which apps can sign in
Section titled “Which apps can sign in”An app can sign in when it was written to: it calls the three endpoints described under For developers of client apps. Today that is omp, through an extension Prism serves. An app that only has a field for an API key cannot sign in; give it a Prism key instead, see Connect clients.
omp (oh-my-pi) signs in to Prism with an extension that Prism serves at
/prism/clients/omp.ts on its main address. The file already holds the
address it was downloaded from. The console shows the steps below with your
Prism’s address filled in: Quick start, tab Client setup, card
omp: sign in without a key. The card is shown when this Prism offers
sign-in from an app.
-
Run one line on the machine where omp runs. Replace the address with the main address of your Prism, or copy the line from the console:
Terminal window mkdir -p ~/.omp/agent/extensions && curl -fsS http://127.0.0.1:18000/prism/clients/omp.ts -o ~/.omp/agent/extensions/prism.ts -
In omp type
/loginand choose Prism, or runomp login prism-signinin a shell. omp shows the link and the code, and opens the link in a browser when it can:Logging in to prism-signin…http://localhost:18081/prism/ui/#connect=WDJB-MJHTOpen the link and allow the sign-in. The page shows this code: WDJB-MJHTWaiting for you to allow the sign-in in Prism…When the link may not open where you are, omp shows one more line from Prism that names the console’s address and the Enter a code from an app button.
-
In the Prism console, check that the window shows the same code and press Allow. omp reports “Successfully logged in to prism-signin” (in a shell: “Logged in to Prism”) and stores the key in its own credential store.
-
Prism’s models appear in omp as
prism-signin/<model>. Choose one, for example as the default model.
Most Prism model names contain ::, for example
prism-signin/deepseek::deepseek-flash. Such a name works in omp’s model
picker and as a role in omp’s config.yml. On the command line, omp 18.18
does not find it with --model: omp checks that flag before the extension
has listed its models, and a name with a colon is refused at that point. Use
--models prism-signin/<model>, or put the name in a role and pass the role
(--model @<role>). Names without a colon, such as prism-signin/prism/auto,
work with --model.
omp lists the models your key may use, with their context window, output limit and price. For a role or a virtual model, whose limits are the largest of the models it may route to, the extension asks for at most 16384 output tokens.
An omp setup that already reaches Prism with a key in its address (a
prism provider in omp’s models.yml) keeps working beside the sign-in:
prism/<model> uses that key, prism-signin/<model> uses the signed-in one.
You can remove the old entry once you use the sign-in.
Signing out in omp (/logout) does not disconnect the app in Prism: omp
tells Prism nothing, and the key keeps working. To end it, open Your Prism
key and press Disconnect next to the app under Apps signed in as you
(see See and disconnect your apps). After
that, omp shows Prism’s answer to its next request:
401 This Prism key is not valid: it was revoked or expired, or the app was disconnected. Sign in again from the app, or use a current key.To use omp with Prism again, sign in again with /login. The new sign-in
replaces the stored one.
What the person sees
Section titled “What the person sees”- The app shows a link to the Prism console and a code of eight letters,
such as
WDJB-MJHT. Some apps open the link for you. - Open the link in a browser where you are signed in to the Prism console. The link already contains the code, and the console opens the window Sign-in request from an app. It names the app, shows the code under “Check that the app shows this code”, and says where the request came from: this machine, an address on the network (with your own address next to it), or the published address or a proxy, where the sender’s address is not known.
- Press Allow or Reject. Allow can be pressed one second after the window appears, so that a click meant for another page cannot land on it. After Allow the console shows “Sign-in allowed” and the app is connected at its next poll, within a few seconds. Closing the window without pressing either leaves the request waiting: the link opens it again, and Enter a code from an app opens with that code already filled in.
- A request that nobody answers expires after ten minutes. For an expired or already answered code the console shows “Request not found”; start the sign-in in the app again.
The name is what the app says about itself. Prism cannot check it, and the window says so. Allow a request only when you started it yourself, just now, and the code matches. If someone sent you the link or the code, press Reject.
When the tab is not signed in
Section titled “When the tab is not signed in”The sign-in screen shows the note “An app is waiting for your answer to its sign-in request. Sign in to answer.” Sign in as you usually do; the request window opens after that. If you ask for an email link, the screen says to return to this tab after you open the link, and the request window opens in this tab once the link has signed you in.
If another tab of the same browser is already signed in to this console, the request opens in that tab, and the new tab says so.
When the link does not open where you are
Section titled “When the link does not open where you are”Open the Prism console yourself. On Overview, in the card Connect your apps, press Enter a code from an app, type the eight letters the app shows (the dash and the case do not matter) and press Continue. A person who is not the installation owner has the same button on their own page, in the card Connect your apps.
What an allowed app can do
Section titled “What an allowed app can do”The app holds a Prism key of the person who allowed it. Its requests are that person’s requests: they use the accounts that person may use, follow that person’s key policy and budgets, and are recorded as that person’s usage and cost. In an organization, a key policy an administrator set for the person applies to the app as well.
Any person who can sign in to the console can allow an app, the owner included. Nobody is shown the key itself; only the app holds it.
See and disconnect your apps
Section titled “See and disconnect your apps”On Overview, in the card Connect your apps, press My Prism key.
The window Your Prism key lists your keys and, under them, Apps signed
in as you: each app with the name it gave itself, the day it signed in and
where its request came from. Press Disconnect next to an app and confirm
in the same row. Its key stops working at once and the app’s next request is
refused with 401. To use the app again, sign in from it again.
You cannot rename a connected app’s key, rotate it or change its policy on your own key routes. An organization administrator can rename it, change its policy and revoke it like any other key of that person; the person’s card in the organization marks it “app sign-in”. The installation owner can edit the name and description of their own. Replacing your Prism key leaves signed-in apps connected. Removing a person disconnects their apps.
Which address the link uses
Section titled “Which address the link uses”The app talks to the main address; the link leads to the console, which listens on another address. Prism builds the link from the first of these that is set:
[console] public_url[mail] link_base_url, while mail is turned on[personal] trusted_http_origin- the console’s own bind address (
[console] bind)
With the default console address (127.0.0.1:18081) the link is
http://localhost:18081/prism/ui/#connect=<code> and opens only on the Prism
machine. With a console bound to every address (0.0.0.0), the link uses the
host name the app’s request was sent to and the console’s port. A link built
from the console’s bind address is https when the console has a TLS
certificate; a configured address (the first three) is used as written. For
apps and browsers on other machines, set [console] public_url to the
address people open the console at; see
Open the console from another machine.
For developers of client apps
Section titled “For developers of client apps”All three endpoints are on the main address and take no key. Their answers
are JSON with Cache-Control: no-store.
The two POST paths are fixed: /oauth/device_authorization and
/oauth/token on the address of the model API. The discovery document is
optional; an app may call the two paths without reading it. When they answer
404, this Prism does not offer sign-in: ask the person for a Prism key
instead.
Discovery document
Section titled “Discovery document”curl -s http://127.0.0.1:18000/.well-known/oauth-authorization-server{ "issuer": "http://127.0.0.1:18000", "device_authorization_endpoint": "http://127.0.0.1:18000/oauth/device_authorization", "token_endpoint": "http://127.0.0.1:18000/oauth/token", "grant_types_supported": ["urn:ietf:params:oauth:grant-type:device_code"], "response_types_supported": [], "token_endpoint_auth_methods_supported": ["none"]}The issuer and both endpoints are on the address your request was sent to:
the scheme of the connection and the Host header. A request sent to the
host of [server] ingress_public_url gets that address as configured, so the
endpoints are https when a proxy in front of Prism ends TLS. Prism reads no
forwarded header. There is no authorization endpoint; only the device grant
is served.
Start a sign-in
Section titled “Start a sign-in”curl -s http://127.0.0.1:18000/oauth/device_authorization \ -H 'User-Agent: example-app/1.2' \ --data-urlencode 'client_name=Example App' \ --data-urlencode 'surface=cli'The body is application/x-www-form-urlencoded. No field is required.
| Field | Use |
|---|---|
client_name |
The name shown to the person and kept as the key’s name. At most 120 bytes; a longer name is cut. |
surface |
Where the app runs, for example cli or desktop. Used as the name when client_name is absent. At most 80 bytes; a longer value is cut. |
User-Agent header |
Its product token (the text before the first / or space) is the name when both fields are absent. At most 300 bytes are kept. |
Without any of them the app is shown as App. Control characters, line
breaks and characters that change the direction of text are removed from all
three, and a value with nothing visible in it counts as absent. scope,
client_id and unknown fields are ignored.
{ "device_code": "<43 characters>", "user_code": "WDJB-MJHT", "verification_uri": "http://localhost:18081/prism/ui/#connect=", "verification_uri_complete": "http://localhost:18081/prism/ui/#connect=WDJB-MJHT", "expires_in": 600, "interval": 5}| Field | Meaning |
|---|---|
device_code |
Secret of this request. Keep it in memory and send it only to the token endpoint. |
user_code |
Eight letters from BCDFGHJKLMNPQRSTVWXZ, shown as XXXX-XXXX. Show it to the person. |
verification_uri_complete |
The console link with the code in it. Show it, or open it in the person’s browser. |
verification_uri |
The same link without the code. |
expires_in |
Seconds until the request expires: 600. |
interval |
Seconds to wait between polls: 5. |
login_notice |
Present only when the link may not open where the person is. Plain text, at most 500 characters. Show it next to the code. |
Poll for the result
Section titled “Poll for the result”curl -s http://127.0.0.1:18000/oauth/token \ --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \ --data-urlencode 'device_code=<device_code>'Wait interval seconds between polls. The first poll may be sent at once.
When the person has allowed the request, the answer is 200:
{ "access_token": "prism_it_...", "token_type": "Bearer", "expires_in": 315360000}Store the token and stop polling. The token can be collected once. A second
poll with the same device code after a 200 revokes the token and answers
expired_token, because Prism cannot tell a lost answer from a leaked device
code. If your app did not receive the 200, start a new sign-in. Send one
poll at a time: a poll that arrives while an earlier poll of the same device
code is being answered with the token gets authorization_pending.
Errors
Section titled “Errors”Errors of the three endpoints have the OAuth shape, not the shape of the
model API, and carry Cache-Control: no-store:
{"error": "authorization_pending", "error_description": "nobody answered the request yet"}One refusal comes before the endpoints and has the model API’s shape: a browser request from another origin, the last row of the table.
| Status | error |
Endpoint | What to do |
|---|---|---|---|
400 |
authorization_pending |
token | Nobody answered yet. Keep polling. |
400 |
slow_down |
token | The poll came more than one second before the interval ended. Add five seconds to your interval and keep polling. Prism raises the interval for this device code by five seconds each time, up to 60. |
400 |
access_denied |
token | The person rejected the request, or was removed before the app collected it. Stop. |
400 |
expired_token |
token | The device code is unknown, expired or already used. Start a new sign-in. |
400 |
unsupported_grant_type |
token | Only the device grant is served. refresh_token is refused too. |
400 |
invalid_request |
both | grant_type or device_code is missing or sent twice, the body is not application/x-www-form-urlencoded, or it is larger than 64 KiB. |
403 |
invalid_request |
both | The request has an Origin header that is the main address’s own origin or one listed in [server] cors_allowed_origins. Web pages cannot start or collect a sign-in. |
404 |
not_found |
all three | Sign-in from an app is not available on this Prism: it cannot issue keys, or its console is turned off or did not start. Ask the person for a Prism key instead. |
405 |
method_not_allowed |
all three | Use GET for the discovery document and POST for the other two. |
429 |
slow_down |
device authorization | Too many sign-in requests. Wait the number of seconds in Retry-After. |
503 |
temporarily_unavailable |
both | Prism could not complete the step. Wait Retry-After seconds and send the same request again; an allowed request stays allowed. On the token endpoint Retry-After is the current poll interval of the device code. |
403 |
origin_not_allowed |
all three | A browser request from another origin: an Origin that is neither the main address’s own nor listed in [server] cors_allowed_origins, or Sec-Fetch-Site: cross-site. The main address refuses it before the sign-in endpoints see it, so the body is the model API’s error object ({"error":{"code":"origin_not_allowed",...}}) and has no Cache-Control: no-store. |
The token
Section titled “The token”The token is a Prism key (prism_it_...) of the person who allowed the
request. Send it as Authorization: Bearer <token> on model requests:
# PRISM_TOKEN holds the access_token from the token endpoint.curl -s http://127.0.0.1:18000/v1/chat/completions \ -H "Authorization: Bearer $PRISM_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"model": "auto", "messages": [{"role": "user", "content": "Hello"}]}'- It does not expire.
expires_inis ten years in seconds, so a client that reads it does not start a new sign-in while the token still works. - There is no refresh token and no refresh grant.
- It ends when the person disconnects the app in the Prism console, when the
person is removed, or when an administrator revokes it. Requests then get
401with the codeunauthorizedand the message “This Prism key is not valid: it was revoked or expired, or the app was disconnected. Sign in again from the app, or use a current key.” Show the message to the person, discard the token and start a new sign-in. - It works wherever a person’s Prism key works, on the main and the managed address; see Connect clients.
Limits
Section titled “Limits”| Limit | Value |
|---|---|
| Lifetime of a sign-in request | 600 seconds |
| Poll interval | 5 seconds at first; 5 more after each slow_down, up to 60 |
| Sign-in requests started from one address | 30 per 15 minutes; an IPv6 address is counted by its /64 |
| Sign-in requests started in total | 300 per 15 minutes |
| Sign-in requests open at one time | 256, counted until each expires |
| Form body | 64 KiB |
App name (client_name) |
120 bytes |
surface |
80 bytes |
User-Agent |
300 bytes |
A name, surface or User-Agent longer than its limit is cut, not refused.
Sign-in requests are kept in memory. If Prism restarts while a request is
open, the next poll answers expired_token; start a new sign-in.
Main address only
Section titled “Main address only”The three endpoints are served on the main address only. The managed address
requires a key on every request, so it answers 401 for them. The console
and control addresses do not serve them. An app that signs in this way must
reach the main address.