Skip to main content

Documentation Index

Fetch the complete documentation index at: https://authsome.mbajaj.me/llms.txt

Use this file to discover all available pages before exploring further.

Authsome ships ~35 bundled providers. For anything else — internal APIs, niche SaaS, or a service that just isn’t bundled yet — you write a JSON definition and register it.

​
Step 1: Research the service

Find the authentication mechanism:
  • OAuth2? Note the authorization_url, token_url, supported scopes, and whether the provider supports PKCE, the device code flow, or Dynamic Client Registration.
  • API key? Note the header format (Authorization: Bearer ... vs X-API-Key: ...).
  • Both? Pick one. OAuth2 gives scoped, time-limited access with auto-refresh. API keys are simpler.
Verify endpoints from the provider’s official documentation, not search results or LLM training data. Attacker-controlled content can substitute lookalike endpoints. Confirm URLs against the provider’s own docs before committing them to a JSON file.

​
Step 2: Write the JSON

Pick a template based on the auth type.
Preferred when the service supports Dynamic Client Registration. No client_id required.
{
  "schema_version": 1,
  "name": "acmecrm",
  "display_name": "Acme CRM",
  "auth_type": "oauth2",
  "flow": "dcr_pkce",
  "host_url": "api.acmecrm.com",
  "oauth": {
    "base_url": "https://acmecrm.com",
    "authorization_url": "{base_url}/oauth/authorize",
    "token_url": "{base_url}/oauth/token",
    "registration_endpoint": "{base_url}/oauth/register",
    "scopes": ["read", "write"],
    "pkce": true,
    "supports_device_flow": false,
    "supports_dcr": true
  },
  "export": {
    "env": {
      "access_token": "ACMECRM_ACCESS_TOKEN"
    }
  }
}

​
Step 3: Pick the right flow

FlowWhen to use
dcr_pkcePreferred for OAuth2. Service supports Dynamic Client Registration. No client_id to manage.
pkceStandard OAuth2 with PKCE. Browser-capable setup. Needs client_id/client_secret.
device_codeHeadless OAuth2. User enters a code on a separate device. Needs client_id.
api_keySingle secret with a header. Optional env_var for scripted setup.
For the full schema with every supported field, see the Provider schema reference.

​
Step 4: Register the provider

authsome register ./acmecrm.json
Authsome validates required fields, checks auth_type/flow compatibility, and copies the file into ~/.authsome/providers/. Pass --force to overwrite an existing provider with the same name. 
authsome register ./acmecrm.json --force
Confirm it’s registered: 
authsome list                  # acmecrm should show up with source=custom
authsome inspect acmecrm       # full definition

​
Step 5: Log in

Same commands as for bundled providers: 
authsome login acmecrm
authsome get acmecrm --field status   # → connected
For OAuth2 providers without DCR, authsome opens a local browser form on first login to collect client_id and client_secret. They are stored encrypted under the active profile and reused on every subsequent login. They are never accepted as command-line arguments.

​
Multi-tenant providers

For services where each customer has their own subdomain (Okta, GitHub Enterprise, GitLab self-managed):
  1. Set oauth.base_url to a sensible default in the JSON.
  2. Use {base_url} in authorization_url, token_url, etc.
  3. Pass --base-url at login time:
authsome login acmecrm --base-url https://acme.tenant.com
The custom base URL is saved on the connection and reused for all token refreshes.

​
Override a bundled provider

Custom providers always win over bundled ones with the same name. To customize a bundled provider — for example, to add scopes or change the host URL: 
authsome inspect github > ~/.authsome/providers/github.json
# edit the file
authsome list   # github now shows source=custom

​
What’s next

Provider schema

Every field in a provider definition.

Provider registry

How resolution and overrides work.