> ## 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.

# Register an OAuth client

> OAuth 2.1 Dynamic Client Registration (RFC 7591). Registration is authenticated: the
caller must present a valid HQ session or token, and the resulting client is owned
by that user. Validates the submitted JSON metadata (redirect URIs must be https or
http loopback with no fragment; scopes must be known capability scopes;
token_endpoint_auth_method none yields a public client, client_secret_post/basic a
confidential one). Returns 201 with the new client_id, a registration_access_token,
and, for confidential clients, a client_secret (the secret and registration token
are shown only once), plus a registration_client_uri for managing the client.
Registered clients are always treated as third-party and shown the consent screen,
and each account is capped on how many it may register.

## Dynamic client registration (RFC 7591)

Registers a new OAuth client and returns its `client_id` and registration metadata. Public clients (e.g. browser apps) use PKCE and have no secret. Provide your `redirect_uris` and the scopes the client may request. Afterwards, manage the registration with [Get](/api-reference/auth/get-client) / [Update](/api-reference/auth/update-client) / [Delete](/api-reference/auth/delete-client) using the returned credentials.


## OpenAPI

````yaml POST /v1/oauth/register
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/register:
    post:
      tags:
        - auth
      summary: Register an OAuth client
      description: >-
        OAuth 2.1 Dynamic Client Registration (RFC 7591). Registration is
        authenticated: the

        caller must present a valid HQ session or token, and the resulting
        client is owned

        by that user. Validates the submitted JSON metadata (redirect URIs must
        be https or

        http loopback with no fragment; scopes must be known capability scopes;

        token_endpoint_auth_method none yields a public client,
        client_secret_post/basic a

        confidential one). Returns 201 with the new client_id, a
        registration_access_token,

        and, for confidential clients, a client_secret (the secret and
        registration token

        are shown only once), plus a registration_client_uri for managing the
        client.

        Registered clients are always treated as third-party and shown the
        consent screen,

        and each account is capped on how many it may register.
      operationId: register_client
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientMetadata'
        required: true
      responses:
        '201':
          description: >-
            Registered client (client_id + one-time secret/registration token),
            RFC 7591
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientInfo'
        '400':
          description: invalid_redirect_uri / invalid_scope / invalid_client_metadata
        '401':
          description: registration requires an authenticated HQ session or token
      security:
        - bearer_pat: []
        - oauth2: []
components:
  schemas:
    ClientMetadata:
      type: object
      properties:
        client_name:
          type:
            - string
            - 'null'
        grant_types:
          type:
            - array
            - 'null'
          items:
            type: string
        redirect_uris:
          type: array
          items:
            type: string
        response_types:
          type:
            - array
            - 'null'
          items:
            type: string
        scope:
          type:
            - string
            - 'null'
          description: Space-delimited capability scopes the client may request.
        token_endpoint_auth_method:
          type:
            - string
            - 'null'
    ClientInfo:
      type: object
      required:
        - client_id
        - client_id_issued_at
        - registration_client_uri
        - redirect_uris
        - client_name
        - token_endpoint_auth_method
        - grant_types
        - response_types
        - scope
      properties:
        client_id:
          type: string
        client_id_issued_at:
          type: integer
          format: int64
        client_name:
          type: string
        client_secret:
          type:
            - string
            - 'null'
        client_secret_expires_at:
          type:
            - integer
            - 'null'
          format: int64
        grant_types:
          type: array
          items:
            type: string
        redirect_uris:
          type: array
          items:
            type: string
        registration_access_token:
          type:
            - string
            - 'null'
        registration_client_uri:
          type: string
        response_types:
          type: array
          items:
            type: string
        scope:
          type: string
        token_endpoint_auth_method:
          type: string
  securitySchemes:
    bearer_pat:
      type: http
      scheme: bearer
      bearerFormat: hq_pat
      description: 'Personal Access Token. Send as `Authorization: Bearer hq_pat_...`.'
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hq.zone/v1/oauth/authorize
          tokenUrl: https://api.hq.zone/v1/oauth/token
          refreshUrl: https://api.hq.zone/v1/oauth/token
          scopes:
            admin: Administer the workspace (users, settings, integrations)
            agents:read: View the agents in your workspace
            agents:write: Create and configure agents
            billing:read: View usage and billing information
            conversations:read: Read your conversations and their messages
            conversations:write: Start conversations and send messages on your behalf
            documents:read: Read your documents library
            documents:write: Upload and manage documents in your library
            memory:read: Read what the assistant remembers about you
            memory:write: Correct or delete what the assistant remembers
            schedules:read: View your scheduled tasks
            schedules:write: Create and manage scheduled tasks
            tables:read: Read your tables and their rows
            tables:write: Create tables and add, edit, or delete rows

````