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

# Get Access Token

> Exchange API client credentials for a bearer token.



## OpenAPI

````yaml POST /v1/auth/token
openapi: 3.0.3
info:
  title: DynamoSQL API
  version: 0.1.0
  license:
    name: Proprietary
    url: https://dynamosql.com
  description: >
    Complete API for DynamoSQL — authentication, SQL query planning and

    execution, schema management, and usage metering.


    All endpoints are reachable at `api.dynamosql.com`.


    **Authentication** uses `POST /v1/auth/token` with your API client

    credentials. See the [Authentication
    guide](https://docs.dynamosql.com/guides/authentication)

    for the full token exchange flow.


    **API client scopes** control which endpoints a programmatic client can
    access.

    Valid scopes: `query`, `schemas:read`, `schemas:write`, `usage:read`.

    Endpoints note their required scope in their description.


    **Error responses** always follow the same envelope:

    ```json

    { "success": false, "error": { "message": "..." } }

    ```
servers:
  - url: https://api.dynamosql.com
    description: Production
security:
  - cognitoJwt: []
tags:
  - name: Authentication
    description: >
      Obtain a JWT bearer token using your API client credentials. This token is
      required for all other endpoints. See the Authentication guide for details
      on the token exchange flow and scope management.
  - name: Query
    description: SQL planning and execution.
  - name: Schemas
    description: >
      Connect DynamoSQL to DynamoDB tables in your AWS account. A schema pairs a
      name with the IAM role and AWS region DynamoSQL uses to assume
      cross-account access.
  - name: Usage
    description: Metered usage — requests, rows returned, and DynamoDB read units.
paths:
  /v1/auth/token:
    post:
      tags:
        - Authentication
      summary: Get access token
      description: >
        Exchange API client credentials for a bearer token. The returned
        `accessToken` is a JWT valid for one hour.
      operationId: authToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - clientId
                - clientSecret
              properties:
                clientId:
                  type: string
                  description: The API client ID from the DynamoSQL portal.
                clientSecret:
                  type: string
                  description: The API client secret. Treat as a password.
      responses:
        '200':
          description: Authentication successful.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          accessToken:
                            type: string
                            description: JWT bearer token.
                          refreshToken:
                            type: string
                            description: Token used to obtain a new access token.
                          expiresIn:
                            type: integer
                            description: Token lifetime in seconds.
                            example: 3600
                          tokenType:
                            type: string
                            example: Bearer
              example:
                success: true
                data:
                  accessToken: eyJhbGciOiJSUzI1NiIs...
                  refreshToken: eyJjdHkiOiJKV1QiLCJl...
                  expiresIn: 3600
                  tokenType: Bearer
        '400':
          description: Missing or invalid request body fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '401':
          description: Invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
      security: []
components:
  schemas:
    ApiResponse:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          description: >
            `true` when the request was processed without errors, `false`
            otherwise. Always present.
        data: {}
        error:
          $ref: '#/components/schemas/ApiError'
    ApiError:
      type: object
      description: Present in the response body when `success` is `false`.
      properties:
        message:
          type: string
          description: Human-readable description of what went wrong.
        code:
          type: string
          description: Machine-readable error code, when available.
        requestId:
          type: string
          description: |
            Request correlation ID. Include this when contacting support.
  securitySchemes:
    cognitoJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Bearer token obtained from `POST /v1/auth/token`. Pass in the
        `Authorization` header as `Bearer <token>`.

````