> ## Documentation Index
> Fetch the complete documentation index at: https://authsome.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Headless setup with device code

> Authenticate over SSH or in CI without a local browser by using the OAuth2 Device Authorization Grant.

The PKCE flow needs a local browser for the OAuth callback. On a remote SSH session, in CI, or on a headless server, there is no browser available. Use the **Device Code flow** instead: you log in on a separate device, and Authsome polls the token endpoint until you authorize.

## Prerequisites

The provider must support the device authorization grant. In a provider definition, that means:

```json theme={null}
{
  "oauth": {
    "supports_device_code": true,
    "device_authorization_url": "https://github.com/login/device/code"
  }
}
```

GitHub, Google, Microsoft, and many others support it. Check `authsome inspect <provider>` for `supports_device_code: true`. [Postiz](/integrations/oauth/postiz) is the only bundled provider that defaults to the device code flow.

## Run the login

```bash theme={null}
authsome login github --flow device_code
```

The terminal prints something like:

```text theme={null}
Visit https://github.com/login/device on any device with a browser
and enter the user code: WDJB-MJHT

Waiting for authorization...
```

<Steps>
  <Step title="Open the URL on any device">
    On your laptop, phone, or any machine with a browser, visit the URL printed in the terminal.
  </Step>

  <Step title="Enter the user code">
    Type or paste the user code (`WDJB-MJHT` in the example above) into the form.
  </Step>

  <Step title="Approve">
    Authorize the app and approve the requested scopes.
  </Step>

  <Step title="Wait for the poll to complete">
    Authsome polls the token endpoint at the provider's recommended interval. Once you approve, the next poll succeeds and the terminal prints `Successfully logged in to github (default).`
  </Step>
</Steps>

## When to choose device code

Use the device code flow when:

* You are SSHed into a remote server and don't want to set up X11 forwarding.
* You are running setup in a CI pipeline that has terminal output but no browser.
* You are inside a Docker container with no exposed ports back to your laptop.

For GitHub specifically, even when a local browser is available, the device code flow can be useful, it avoids registering an OAuth app entirely (GitHub's device flow uses the public GitHub OAuth client by default).

## Use it in CI

In CI, you can capture the authorization URL and code from the command output and surface them in the build log so a human can complete the authorization:

```bash theme={null}
authsome login github --flow device_code 2>&1 | tee login.log
```

The login command waits until the device flow either completes, expires, or is cancelled. For unattended CI you typically log in once on a developer machine and then copy the encrypted vault data (or, more often, run the agent only on machines that already have an authenticated vault).

## API key providers

API-key providers don't have a device flow. On a headless machine without `DISPLAY`, authsome's API-key flow falls back to **masked terminal input** through `getpass`:

```bash theme={null}
ssh server.example.com
authsome login openai
# OpenAI API key: ********  (typed input is not echoed)
```

The browser bridge is skipped automatically when no display is available.

## Override the default flow per provider

To make `device_code` the default for a provider, for example, you always log in to GitHub from servers, drop a custom JSON file at `~/.authsome/providers/github.json` with `"flow": "device_code"`. See [Provider registry](/concepts/provider-registry) for how overrides work.

## What's next

<Columns cols={2}>
  <Card title="Log in with OAuth" icon="right-to-bracket" href="/guides/login-with-oauth">
    The full OAuth login guide, including PKCE and DCR.
  </Card>

  <Card title="Run agents with the proxy" icon="shield-halved" href="/guides/run-agents-with-proxy">
    What to do once you're authenticated.
  </Card>
</Columns>