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

# Refresh Access Token

> Exchange a refresh token for a new access token.



## OpenAPI

````yaml POST /v1/auth/refresh
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/refresh:
    post:
      tags:
        - Authentication
      summary: Refresh access token
      description: >
        Exchange a refresh token for a new access token. No new refresh token is
        issued.
      operationId: authRefresh
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - refreshToken
              properties:
                refreshToken:
                  type: string
                  description: The refresh token from a previous authentication.
      responses:
        '200':
          description: Token refreshed successfully.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          accessToken:
                            type: string
                            description: New JWT bearer token.
                          expiresIn:
                            type: integer
                            description: Token lifetime in seconds.
                            example: 3600
                          tokenType:
                            type: string
                            example: Bearer
        '400':
          description: Missing or invalid request body fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '401':
          description: Invalid or expired refresh token.
          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>`.

````