Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

OAuth

HQ can act as an OAuth 2.0 Authorization Server (AS).

It is embedded -- no external AS is required. The implementation lives in internal/oauth2/ and follows the Authorization Code grant flow (RFC 6749 Section 4.1), with optional PKCE (RFC 7636) and support towards OAuth 2.1.

Discovery and registration

  1. Server Metadata (RFC 8414): Clients discover HQ's OAuth endpoints via GET /.well-known/oauth-authorization-server, which returns the issuer URL, endpoint URLs, supported grant types, scopes, token endpoint auth methods, and PKCE support.

  2. Dynamic Client Registration (RFC 7591): When the dcr config flag is enabled, clients can self-register via POST /oauth2/register. DCR-created apps are placed into a configured default org. Each registered app receives a client_id and client_secret (bcrypt-hashed at rest).

  3. Manual Registration: Apps can also be created via the HQ API (provenance "api" vs "dcr").

Configuration

Add to the HQ config.

 auth:
    oauth2:
      authorizationServer:
        enabled: true
        issuerURL: "https://hq.example.com"
  issuerURL is the only field that's conditionally required (when enabled is true)

For the full list of settings, see the Configuration Reference.

Last updated

Was this helpful?