# Device flow for CLIs

Sign people in from a terminal or a device without a browser redirect, using the OAuth device authorization grant (RFC 8628).

URL: https://osintverse.com/docs/oauth/device-flow

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](https://osintverse.com/docs/authentication)). The device flow here only proves who someone is.

## 1. Ask for a code

```bash
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

```bash
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.