---
title: Auth
description: OAuth2 authentication flows
icon: Lock
---

Define OAuth2 profiles in `config.toml`, then reference them from templates.

## Supported Flows

<Tabs>
  <Tab value="device_code" label="Device Code">
    Best for CLI tools. The user visits a URL to authorize.

    **Required:** `token_url`, `device_authorization_url`

    ```toml
    [auth.profiles.my_provider]
    flow = "device_code"
    client_id = "your-client-id"
    token_url = "https://provider.example.com/oauth/token"
    device_authorization_url = "https://provider.example.com/oauth/device/code"
    scopes = ["read:data"]
    ```

  </Tab>
  <Tab value="auth_code_pkce" label="Auth Code PKCE">
    Opens a browser and handles a local callback.

    **Required:** `token_url`, `authorization_url`

    ```toml
    [auth.profiles.my_provider]
    flow = "auth_code_pkce"
    client_id = "your-client-id"
    token_url = "https://provider.example.com/oauth/token"
    authorization_url = "https://provider.example.com/oauth/authorize"
    redirect_url = "http://127.0.0.1:8976/callback"
    scopes = ["read:data"]
    ```

  </Tab>
  <Tab value="client_credentials" label="Client Credentials">
    Machine-to-machine auth without user interaction.

    **Required:** `token_url`

    ```toml
    [auth.profiles.my_provider]
    flow = "client_credentials"
    client_id = "your-client-id"
    client_secret_key = "my_provider.client_secret"
    token_url = "https://provider.example.com/oauth/token"
    scopes = ["read:data"]
    ```

  </Tab>
</Tabs>

### Optional Fields

All flows also accept:

| Field                  | Description                                          |
| ---------------------- | ---------------------------------------------------- |
| `client_secret_key`    | Secret key in earl's keychain for the client secret.  |
| `issuer`               | Token issuer URL for validation.                     |
| `redirect_url`         | Callback URL (required for `auth_code_pkce`).        |
| `scopes`               | List of OAuth scopes to request.                     |
| `use_auth_request_body`| Send credentials in request body instead of header.  |

## Using Auth in Templates

```hcl
auth {
  kind = "oauth2_profile"
  profile = "my_provider"
}
```

## Commands

```bash
earl auth login my_provider    # Start OAuth login flow
earl auth status my_provider   # Check token status
earl auth refresh my_provider  # Force token refresh
earl auth logout my_provider   # Remove stored tokens
```

The profile name must match the key in `[auth.profiles.<name>]` exactly.
