Skip to content

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.

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.

  1. 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
  2. In omp type /login and choose Prism, or run omp login prism-signin in 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-MJHT
    Open the link and allow the sign-in. The page shows this code: WDJB-MJHT
    Waiting 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.

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

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.

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.

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.

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.

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.

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:

  1. [console] public_url
  2. [mail] link_base_url, while mail is turned on
  3. [personal] trusted_http_origin
  4. 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.

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.

Terminal window
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.

Terminal window
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.
Terminal window
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 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 is a Prism key (prism_it_...) of the person who allowed the request. Send it as Authorization: Bearer <token> on model requests:

Terminal window
# 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_in is 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 401 with the code unauthorized and 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.
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.

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.