> ## 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 API token

> Creates a new personal access token for the authenticated caller, returning the
plaintext token exactly once (it cannot be retrieved again) along with its id, name,
scopes, and optional expiry. Accepts a name, an optional list of capability scopes
(resource:action, e.g. documents:read; omitting scopes defaults to full non-admin
access), and an optional expires_in_days (omitted means non-expiring). Each scope
must be a known capability or legacy tier, and requesting the admin scope requires
the caller to have the admin role. The token's effective permissions are always
clamped to the caller's role at request time.



## OpenAPI

````yaml POST /v1/api/tokens
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/tokens:
    post:
      tags:
        - tokens
      summary: Create an API token
      description: >-
        Creates a new personal access token for the authenticated caller,
        returning the

        plaintext token exactly once (it cannot be retrieved again) along with
        its id, name,

        scopes, and optional expiry. Accepts a name, an optional list of
        capability scopes

        (resource:action, e.g. documents:read; omitting scopes defaults to full
        non-admin

        access), and an optional expires_in_days (omitted means non-expiring).
        Each scope

        must be a known capability or legacy tier, and requesting the admin
        scope requires

        the caller to have the admin role. The token's effective permissions are
        always

        clamped to the caller's role at request time.
      operationId: create_token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTokenReq'
        required: true
      responses:
        '200':
          description: The new token (plaintext shown once)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTokenResp'
        '400':
          description: Invalid name or scopes
        '403':
          description: Scope requires the admin role
      security:
        - bearer_pat: []
        - oauth2: []
components:
  schemas:
    CreateTokenReq:
      type: object
      required:
        - name
      properties:
        expires_in_days:
          type:
            - integer
            - 'null'
          format: int64
          description: Optional expiry; omitted = non-expiring manual PAT.
        name:
          type: string
        scopes:
          type:
            - array
            - 'null'
          items:
            type: string
          description: >-
            Requested capability scopes (resource:action, e.g.
            `documents:read`).

            Omitted = `["user"]` (full non-admin access, back-compat). Each must

            be a known capability scope or a legacy tier; the effective set is

            still clamped to the caller's role at request time.
    CreateTokenResp:
      type: object
      required:
        - id
        - token
        - name
        - scopes
      properties:
        expires_at:
          type:
            - string
            - 'null'
        id:
          type: string
          format: uuid
        name:
          type: string
        scopes:
          type: array
          items:
            type: string
        token:
          type: string
          description: The plaintext token - shown exactly once, never retrievable again.
  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

````