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

# Get an access token

> Exchange a credential for a short-lived access token (OAuth 2.0, RFC 6749). Supported grant types: `publishable_key`. Refresh and other grants will be added on the same endpoint.



## OpenAPI

````yaml https://api-v3.aui.io/apollo-api/openapi.json post /management/v1/auth/token
openapi: 3.1.0
info:
  title: Apollo API
  description: >-
    Build conversational experiences on your agents and manage them
    programmatically.


    The API has two surfaces:


    - **Messaging** (`/messaging/v1`) — send end-user messages to your agent and
    read conversations back. Replies are available as a single JSON response, a
    Server-Sent Events token stream (`POST /messaging/v1/messages/stream`), or a
    bidirectional WebSocket session (see the companion AsyncAPI document at
    `/asyncapi.yaml`).

    - **Management** (`/management/v1`) — manage agents, their versions,
    projects, and conversation threads.


    **Authentication** — exchange your publishable key for a short-lived access
    token at `POST /management/v1/auth/token`, then send it as `Authorization:
    Bearer <access_token>`. Management endpoints also accept an organization API
    key via the `x-organization-api-key` header.


    **Errors** — every failure returns `{"error": {"code", "message",
    "request_id", "details"}}`. Branch on the stable `code`; include
    `request_id` when contacting support.
  version: 0.1.0
servers:
  - url: https://api-v3.aui.io/apollo-api
security: []
tags:
  - name: Auth
    description: >-
      Exchange a credential for a short-lived access token — start here. Send
      the token as `Authorization: Bearer <access_token>` on every other
      endpoint (management endpoints also accept an organization API key via the
      `x-organization-api-key` header).
  - name: Messaging
    description: >-
      Talk to your agent: send end-user messages (JSON reply or SSE token
      stream), rerun an interaction, and read a conversation's messages and
      reasoning traces. Threads are created automatically on the first message —
      pass the returned `thread_id` to continue a conversation.
  - name: Channels
    description: >-
      Reach end users on WhatsApp and SMS: send the opening message and bind the
      recipient's phone number to a conversation thread; replies flow through
      the same thread.
  - name: Threads
    description: >-
      Conversation threads: list and filter them, fetch one with its transcript
      and traces, and update its title.
  - name: Agents
    description: Create and manage the agents in a project.
  - name: Agent Versions
    description: >-
      An agent's configuration versions: list and inspect them, and publish a
      new live version.
  - name: Projects
    description: Projects group your agents within an organization.
  - name: Health
    description: Service liveness.
paths:
  /management/v1/auth/token:
    post:
      tags:
        - Auth
      summary: Get an access token
      description: >-
        Exchange a credential for a short-lived access token (OAuth 2.0, RFC
        6749). Supported grant types: `publishable_key`. Refresh and other
        grants will be added on the same endpoint.
      operationId: issue_token
      parameters:
        - name: Origin
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Origin
        - name: X-Forwarded-For
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Forwarded-For
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Body
            examples:
              publishable_key:
                summary: Exchange a publishable key
                value:
                  grant_type: publishable_key
                  publishable_key: pk_network_...
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: RFC 6749 §5.2 error response
          content:
            application/json:
              examples:
                invalid_request:
                  value:
                    error: invalid_request
                    error_description: Missing 'grant_type'
                invalid_grant:
                  value:
                    error: invalid_grant
                    error_description: invalid_publishable_key
                unsupported_grant_type:
                  value:
                    error: unsupported_grant_type
                    error_description: grant_type 'foo' is not supported
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '502':
          description: Identity service is unavailable or returned an unexpected response
          content:
            application/json:
              example:
                error: server_error
                error_description: Identity service is unavailable
components:
  schemas:
    TokenResponse:
      properties:
        access_token:
          type: string
          title: Access Token
        token_type:
          type: string
          title: Token Type
          default: Bearer
        expires_in:
          type: integer
          title: Expires In
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
      type: object
      required:
        - access_token
        - expires_in
      title: TokenResponse
      description: |-
        Successful token response (RFC 6749 §5.1), extended with the agent and
        organization behind the exchanged key. Send the token as
        ``Authorization: Bearer <access_token>``; ``agent_id`` is the agent your
        messaging calls run against (``null`` when the key carries no agent).
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````