OAuth authorization endpoint
Starts an OAuth 2.1 authorization-code flow with PKCE, where HQ acts as the authorization server. Requires an active HQ browser session; if the caller is not signed in they are redirected to HQ sign-in and back. Validates the client_id against the client registry, checks that redirect_uri is on the client’s allowlist, requires code_challenge_method=S256, and grants the requested scopes intersected with the client’s allowed scopes (an empty scope param grants all allowed scopes; requesting only disallowed scopes returns invalid_scope). On success it issues a single-use authorization code and redirects to the client’s redirect_uri with code and state query parameters; third-party (non-first-party) clients are first sent to a consent screen unless prior consent already covers the requested scopes.
Browser redirect endpoint (OAuth 2.1)
The start of the authorization-code + PKCE flow. This is a front-channel, browser-redirect endpoint — open it in the user’s browser, don’t call it from a server. HQ authenticates the user (via theirhq-session cookie), then 302-redirects back to your registered redirect_uri with a single-use code.
Standard query parameters apply: response_type=code, client_id, redirect_uri, scope, state, code_challenge, and code_challenge_method=S256. The granted scope is what you request intersected with the client’s allowed scopes, and never exceeds the user’s own role.
Exchange the returned code at the token endpoint. Register a client first via Register an OAuth client, or use a first-party client.