Agents and CLIs

An agent or a CLI that can't open a browser itself signs a person in with the device flow (RFC 8628): it shows a short code, and the person confirms it on their phone or laptop. Make it an app of type agent (Make an app): it's public, has no secret and no redirect URIs.

The flowCopy Anchor Link

1. The agent asks for a code. POST /device/auth on the issuer, with its client_id, the scope it needs (offline_access for a refresh token) and, for an API, its resource. The answer has a device_code, a user_code such as BCDF-GHJK (8 letters from 20 consonants, so none reads as another), a verification_uri and a verification_uri_complete with the code in it, expires_in (10 minutes) and interval (5 seconds).
2. The person confirms it. The agent shows the code and the link, or a QR code of verification_uri_complete. On the brand's page the person signs in, then sees the code large, the agent's name, each scope it asks for in your API's words, and the longest it can act for them, and goes on only if their device shows that code.
3. The agent polls for its tokens. POST /token with grant_type=urn:ietf:params:oauth:grant-type:device_code, its device_code and client_id, no more often than interval: polling sooner answers slow_down. Until the person decides it answers authorization_pending; then the tokens, or access_denied if they cancelled, or expired_token after 10 minutes.

The agent's tokensCopy Anchor Link

Its tokens carry act: { type: 'agent', client_id }, so your API can tell that an agent is acting for the person, and audit rows name both. Its refresh token lives 30 days from the sign-in and isn't extended by use: after that, the person confirms a new code. Ending the person's sessions (a password reset, the tenant ending them) ends the agent's grant too.