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

# Log in with OAuth

> Use the PKCE browser flow to authenticate with GitHub, Google, Linear, and other OAuth2 providers.

OAuth2 providers like GitHub, Google, Linear, Slack, and Notion use a browser-based PKCE flow by default. You authenticate once, and Authsome takes over token refresh from there.

## When to use this flow

Use the PKCE browser flow when:

* Your machine has a graphical browser available.
* You can register an OAuth app with the provider (or the provider supports Dynamic Client Registration, see the note below).

If you are on a remote SSH session, in CI, or on a headless server, use the [Device Code flow](/guides/headless-device-code) instead.

## Register an OAuth app

For services that don't support Dynamic Client Registration, you need to register an OAuth app with the provider once. The redirect URI must be:

```text theme={null}
http://127.0.0.1:7998/auth/callback/oauth
```

This is the only redirect URI authsome listens on for PKCE flows.

GitHub example:

<Steps>
  <Step title="Create a new OAuth app">
    Visit [github.com/settings/developers](https://github.com/settings/developers) and click **New OAuth App**.
  </Step>

  <Step title="Set the redirect URI">
    Set **Authorization callback URL** to `http://127.0.0.1:7998/auth/callback/oauth`.
  </Step>

  <Step title="Save the client ID and secret">
    Keep the **Client ID** and **Client Secret** at hand. Authsome will prompt for them on first login through a secure local browser form. You will not paste them into a terminal.
  </Step>
</Steps>

<Tip>
  For services that support <Tooltip tip="Dynamic Client Registration. The server registers an OAuth client on the fly so the user does not need to pre-register an app.">Dynamic Client Registration (DCR)</Tooltip>, for example, some MCP servers and modern OAuth providers, authsome's `dcr_pkce` flow registers an OAuth client automatically. You skip the app-registration step entirely.
</Tip>

## Run the login

```bash theme={null}
authsome login github
```

This is what happens:

<Steps>
  <Step title="Client credential collection (first time only)">
    Authsome opens a local form at `http://127.0.0.1:7998`. Paste your `client_id` and `client_secret`. They are encrypted and stored in your vault, then reused on every subsequent login.
  </Step>

  <Step title="Authorization redirect">
    A second browser window opens to the provider's authorization page. Approve the requested scopes.
  </Step>

  <Step title="Token exchange">
    The provider redirects back to `http://127.0.0.1:7998/auth/callback/oauth` with an authorization code. Authsome exchanges it for an access token (and a refresh token, if the provider supports them) and stores the encrypted record.
  </Step>

  <Step title="Confirmation">
    The terminal prints `Successfully logged in to github (default).`
  </Step>
</Steps>

<Warning>
  Sensitive values. `client_secret`, access tokens, refresh tokens, are never accepted as command-line arguments. They never appear in shell history or process listings. Authsome collects them through the secure browser bridge or, on headless machines, through masked terminal input.
</Warning>

## Override the flow

The default flow lives in the provider definition. Override it on the command line:

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

Valid values: `pkce`, `device_code`, `dcr_pkce`, `api_key`.

## Custom scopes

Request specific scopes instead of the provider's default set:

```bash theme={null}
authsome login github --scopes "repo,read:user,workflow"
```

The granted scopes are stored on the connection record and visible in `authsome get github`.

## Multi-tenant / self-hosted (Enterprise)

Providers like GitHub Enterprise, Okta, and GitLab self-managed run on per-deployment URLs. Pass `--base-url`:

```bash theme={null}
authsome login github --base-url https://github.acme.com
```

The base URL is saved on the connection and reused for every refresh.

## Multiple connections per provider

The default connection name is `default`. To log in to a second account on the same provider, pass `--connection <name>` to `login` and to every read command. See [Multiple connections per provider](/guides/multiple-connections) for the full pattern.

## Verify the login

```bash theme={null}
authsome list
authsome get github                  # metadata, secrets redacted
authsome get github --field status   # → connected
```

## Re-login

If a provider is already `connected`, `authsome login <provider>` exits with an error. To overwrite an existing connection:

```bash theme={null}
authsome login github --force
```

This skips the "already connected" guard and runs the flow again, replacing the stored credentials. Use `authsome revoke github` first if you want to invalidate the old token at the provider as well.

## What's next

<Columns cols={2}>
  <Card title="Run agents with the proxy" icon="shield-halved" href="/guides/run-agents-with-proxy">
    Inject the access token into outbound requests without exposing it.
  </Card>

  <Card title="Headless device code" icon="server" href="/guides/headless-device-code">
    Authenticate over SSH or in CI when no local browser is available.
  </Card>
</Columns>