> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hq.zone/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 their `hq-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](/api-reference/auth/oauth-token). Register a client first via [Register an OAuth client](/api-reference/auth/register-client), or use a first-party client.


## OpenAPI

````yaml GET /v1/oauth/authorize
openapi: 3.1.0
info:
  title: HQ API
  description: >-
    Public HTTP API for HQ. Authenticate with a Personal Access Token
    (`Authorization: Bearer hq_pat_...`) for server-side integrations, or an
    OAuth 2.1 authorization-code + PKCE flow for browser apps acting on a user's
    behalf. Both grant from the same resource:action scope vocabulary; an
    endpoint's required scope is listed under its `security`.
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  version: 1.0.0
servers:
  - url: https://api.hq.zone
    description: HQ API (production)
security: []
tags:
  - name: me
    description: The signed-in user's own account
  - name: conversations
    description: Conversations and their messages
  - name: documents
    description: The content-addressed documents library
  - name: schedules
    description: Scheduled prompts and recurring tasks
  - name: agents
    description: Agents, their skills and integrations
  - name: memory
    description: What the assistant remembers (L5 governance)
  - name: tokens
    description: Personal Access Token management
  - name: billing
    description: Usage and billing
  - name: notifications
    description: In-app notification center
  - name: admin
    description: Workspace administration
  - name: integrations
    description: Workspace integrations (Slack, MCP, skills)
  - name: onboarding
    description: New-workspace onboarding wizard
  - name: auth
    description: Sign-in, sessions, and OAuth
paths:
  /v1/oauth/authorize:
    get:
      tags:
        - auth
      summary: OAuth authorization endpoint
      description: >-
        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.
      operationId: oauth_authorize
      parameters:
        - name: client_id
          in: query
          required: true
          schema:
            type: string
        - name: redirect_uri
          in: query
          required: true
          schema:
            type: string
        - name: code_challenge
          in: query
          required: true
          schema:
            type: string
        - name: code_challenge_method
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: state
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: scope
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
      responses:
        '302':
          description: >-
            Redirect to the client's redirect_uri with ?code=&state=
            (third-party clients hit the consent screen first)
        '400':
          description: invalid_request / unknown client_id / invalid_scope
        '429':
          description: Too many requests (per-IP rate limit)

````