Auth

Earl supports OAuth2 authentication through named profiles defined in config.toml. Profiles handle login, token storage, automatic refresh, and injection into API requests.

Supported Flows

[auth.profiles.github]
flow = "auth_code_pkce"
client_id = "your-github-client-id"
token_url = "https://github.com/login/oauth/access_token"
authorization_url = "https://github.com/login/oauth/authorize"
scopes = ["repo", "read:org"]

[auth.profiles.azure]
flow = "device_code"
client_id = "your-azure-client-id"
token_url = "https://login.microsoftonline.com/common/oauth2/v2.0/token"
device_authorization_url = "https://login.microsoftonline.com/common/oauth2/v2.0/devicecode"
scopes = ["User.Read"]

[auth.profiles.internal_api]
flow = "client_credentials"
client_id = "service-account-id"
client_secret_key = "internal_api.client_secret"
token_url = "https://auth.internal.example.com/oauth/token"
scopes = ["api:read", "api:write"]

earl secrets set internal_api.client_secret

Profile Configuration Reference

Every profile requires flow, client_id, and token_url (or an issuer that provides it via OIDC discovery). Additional fields depend on the flow:

OIDC Discovery

If your identity provider supports OpenID Connect, you can set issuer instead of manually specifying endpoint URLs:

[auth.profiles.okta]
flow = "auth_code_pkce"
client_id = "your-okta-client-id"
issuer = "https://dev-123456.okta.com"
scopes = ["openid", "profile"]

Earl fetches https://dev-123456.okta.com/.well-known/openid-configuration and extracts authorization_endpoint, token_endpoint, and device_authorization_endpoint. Any explicitly set URL in the profile overrides the discovered value.

The issuer URL is validated with the same SSRF checks as other OAuth endpoints -- it must use HTTPS (or HTTP to a loopback address).

Commands

Login

earl auth login github

Starts the OAuth flow defined in the profile. For auth_code_pkce, this opens a browser and starts a local callback server. For device_code, this displays the verification URL and user code. For client_credentials, this exchanges credentials for a token directly.

Check status

earl auth status github

Shows whether a token is stored, when it expires, and which scopes were granted.

Refresh token

earl auth refresh github

Forces a token refresh using the stored refresh token. If no refresh token is available and the flow is client_credentials, earl re-authenticates automatically. For other flows without a refresh token, earl prints an error directing you to run earl auth login.

Logout

earl auth logout github

Deletes the stored token for the profile from the OS keychain.

Token Storage

OAuth tokens are stored in the OS keychain under the key oauth2.<profile>.token. The stored payload is a JSON object containing:

• access_token -- the bearer token
• refresh_token -- if provided by the identity provider
• token_type -- typically Bearer
• expires_at -- expiration timestamp (if the provider returns expires_in)
• scopes -- granted scopes

Tokens are considered expired 30 seconds before their actual expiration time to account for clock skew and network latency.

Token debug output (via RUST_LOG) redacts access_token and refresh_token fields to prevent accidental logging of credentials.

Using Auth in Templates

Reference an OAuth2 profile in a template's auth block:

auth {
  kind    = "oauth2_profile"
  profile = "github"
}

When the template is executed, earl automatically:

1. Loads the stored token for the profile
2. Checks if the token is expired
3. Refreshes the token if needed (using the refresh token or re-authenticating for client credentials)
4. Injects the access token as a Bearer authorization header

If the profile has no stored token and the flow is not client_credentials, earl prints an error directing the user to run earl auth login <profile>.

Endpoint Security

All OAuth endpoint URLs are validated before use:

• Must use https scheme (or http to loopback addresses 127.0.0.1, ::1, localhost for local development)
• Must resolve to public IP addresses (SSRF protection blocks private, reserved, and metadata IPs)
• The same validation applies to OIDC discovery URLs

See Security Model for the full list of blocked IP ranges.