Device flow for CLIs

Apps registered as CLI, desktop, or device can use the device authorization grant. The person approves the sign-in in any browser; your program never handles a redirect.

This is separate from osintverse login in the OSINTverse CLI, which issues an ov_ API key (see Authentication). The device flow here only proves who someone is.

1. Ask for a code

curl -s -X POST https://osintverse.com/api/auth/device/code \
  -d client_id=YOUR_CLIENT_ID \
  -d "scope=openid profile email offline_access"

The response has device_code, user_code, verification_uri, verification_uri_complete, expires_in (ten minutes), and interval (seconds).

2. Show the code

Print verification_uri_complete (it opens https://osintverse.com/oauth/device with the code filled in) and the user_code, so the person can check they match.

3. Poll for tokens

curl -s -X POST https://osintverse.com/api/auth/oauth2/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d client_id=YOUR_CLIENT_ID \
  -d device_code=DEVICE_CODE

Poll every interval seconds. Until the person decides you get authorization_pending; slow down by five seconds on slow_down. access_denied means they cancelled and expired_token means the code ran out. On approval you receive access_token, id_token, and refresh_token (with offline_access).

Storing tokens

Keep the refresh token in the operating system keyring where you can, or in a file only the user can read. Never print it. Use the userinfo_endpoint to show who is signed in.