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

# Exchange OAuth grants for opaque access tokens

> Use HTTP Basic client authentication. Supports client_credentials, authorization_code with S256 PKCE, and refresh_token. Password and implicit grants are intentionally unsupported.



## OpenAPI

````yaml /openapi/v2.json post /oauth/token
openapi: 3.0.3
info:
  title: Vantr Developer API
  version: v2
  description: >-
    OAuth 2.0 developer access for Vantr v2 APIs on api.vantr.ai. Developer API
    for v2 integrations with scoped access to supported resources. Vantr uses
    vantr.ai for marketing, app.vantr.ai for the web application, and
    api.vantr.ai for API traffic. The developer portal and public docs are
    first-class API-host experiences at api.vantr.ai/developer and
    api.vantr.ai/docs. The application and business API uses /v1 on
    api.vantr.ai. Third-party integrations use /v2 on api.vantr.ai. The current
    v2 API includes scoped access for products, product variations, product and
    variation tags, categories and subcategories, vendors, tenant locations,
    orders with order payments, and usage reporting. Bills are a planned public
    resource with constrained lifecycle rules. Server-side callers may use OAuth
    bearer tokens, direct confidential-client Basic authentication with
    client_id and client_secret, or the x-client-id/x-client-secret header pair
    (the legacy x-invoiceedge-client-id/x-invoiceedge-client-secret names remain
    accepted). Requests are rate limited per credential (240/min on /v2, 60/min
    on the OAuth token endpoints) with RateLimit-* response headers and 429 +
    Retry-After when exceeded. /v2 behavior is versioned by release date: send
    the X-API-Version header (YYYY-MM-DD) to pin a release, or omit it to use
    the latest. Unknown versions return 400 unsupported_api_version, and the
    resolved version is echoed in the X-API-Version response header.
servers:
  - url: https://api.vantr.ai
    description: Vantr API
  - url: http://localhost:8080
    description: Local development
security: []
tags:
  - name: OAuth
    description: OAuth 2.0 token, revocation, and introspection endpoints.
  - name: Capabilities
    description: Discover v2 developer resource capabilities.
  - name: Products
    description: Product, variation, tag, and catalog metadata APIs.
  - name: Categories
    description: Category, subcategory, and classification metadata APIs.
  - name: Vendors
    description: Vendor profile APIs.
  - name: Locations
    description: Read-only tenant location APIs for public location_id discovery.
  - name: Orders
    description: Order and order-payment APIs with lifecycle-constrained writes.
  - name: Webhooks
    description: Register webhook endpoints and subscribe to event streams.
  - name: Usage
    description: Public API usage reporting.
externalDocs:
  description: Vantr public API guide, route catalog, and SDK starters.
  url: https://api.vantr.ai/docs
paths:
  /oauth/token:
    post:
      tags:
        - OAuth
      summary: Exchange OAuth grants for opaque access tokens
      description: >-
        Use HTTP Basic client authentication. Supports client_credentials,
        authorization_code with S256 PKCE, and refresh_token. Password and
        implicit grants are intentionally unsupported.
      operationId: exchangeOAuthToken
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                    - client_credentials
                    - authorization_code
                    - refresh_token
                scope:
                  type: string
                  description: >-
                    Required for client_credentials and authorization_code
                    requests. Optional on refresh_token to narrow the refreshed
                    access token.
                  example: products.read categories.read vendors.read locations.read
                code:
                  type: string
                redirect_uri:
                  type: string
                  format: uri
                code_verifier:
                  type: string
                refresh_token:
                  type: string
              required:
                - grant_type
      responses:
        '200':
          description: Opaque bearer token response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          $ref: '#/components/responses/OAuthError'
        '401':
          $ref: '#/components/responses/OAuthError'
      security:
        - BasicClientAuth: []
components:
  schemas:
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          example: 3600
        scope:
          type: string
          example: products.read categories.read vendors.read locations.read
        refresh_token:
          type: string
      required:
        - access_token
        - token_type
        - expires_in
        - scope
    OAuthError:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
  responses:
    OAuthError:
      description: OAuth error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthError'
  securitySchemes:
    BasicClientAuth:
      type: http
      scheme: basic
      description: >-
        Use client_id as username and client_secret as password for confidential
        server-side calls. The application allowed_scopes still gate each /v2
        endpoint; never use this secret in browsers, mobile apps, logs, or query
        strings. Server integrations may alternatively send x-client-id and
        x-client-secret headers (the legacy x-invoiceedge-* names remain
        accepted).

````