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

# Create an OAuth app

> Registers a new OAuth application owned by the authenticated caller, validating the
supplied client metadata (redirect URIs must be https or http loopback with no
fragment, scopes must be known capability scopes). Returns the created app including
its client_id and, for confidential clients, a client_secret, plus a
registration_access_token used for later RFC 7592 management; the secret and
registration token are shown only once and cannot be retrieved again. Each account
is limited in how many apps it may register.



## OpenAPI

````yaml POST /v1/api/oauth/apps
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/api/oauth/apps:
    post:
      tags:
        - tokens
      summary: Create an OAuth app
      description: >-
        Registers a new OAuth application owned by the authenticated caller,
        validating the

        supplied client metadata (redirect URIs must be https or http loopback
        with no

        fragment, scopes must be known capability scopes). Returns the created
        app including

        its client_id and, for confidential clients, a client_secret, plus a

        registration_access_token used for later RFC 7592 management; the secret
        and

        registration token are shown only once and cannot be retrieved again.
        Each account

        is limited in how many apps it may register.
      operationId: create_app
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientMetadata'
        required: true
      responses:
        '200':
          description: The created app (secret + registration token shown once)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedApp'
        '400':
          description: Invalid metadata or scope outside the vocabulary
      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'
    CreatedApp:
      type: object
      required:
        - client_id
        - registration_access_token
        - name
        - client_type
        - redirect_uris
        - scopes
      properties:
        client_id:
          type: string
        client_secret:
          type:
            - string
            - 'null'
          description: >-
            Present only for confidential clients; shown ONCE, never
            retrievable.
        client_type:
          type: string
        name:
          type: string
        redirect_uris:
          type: array
          items:
            type: string
        registration_access_token:
          type: string
          description: The RFC 7592 management bearer; shown ONCE.
        scopes:
          type: array
          items:
            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

````