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

# Get New Access Token from Refresh Token

Generate a new short-lived `access_token` using a valid `refresh_token` previously issued.

> ⚠️ **Important**: This endpoint **must be called from your server**. Never expose `refresh_token` or any sensitive token logic to the frontend or the iframe.

When the `access_token` passed in the iframe query params expires, the Chatzy AI iframe will send a `postMessage` event to the parent window with following JSON payload:

```json theme={null}
{
    type: "[TOKEN_REFRESH]"
    reason: "TokenExpiredError"
}
```

Your client application (the host of the iframe) **must listen for this `postMessage` event**, and **call this `/ai_agent/refresh_token` API from your server** to get a new `access_token` using the stored `refresh_token`.

Once you get the new token, **respond back to the iframe** with following JSON payload:

```json theme={null}
{
  "type": "[TOKEN_REFRESH_RESPONSE]",
  "access_token": "<NEW_ACCESS_TOKEN>"
}
```

The Chatzy AI iframe will update the token internally and continue to make secure API calls using the new token.

> ⚠️ Do not send `refresh_token` to the iframe or store it in localStorage/cookies on the client. Chatzy AI iframe only needs `access_token` to make authorized API calls.


## OpenAPI

````yaml post /ai_agent/refresh_token
openapi: 3.0.0
info:
  title: Chatzy AI API
  version: 1.0.0
  description: >-
    Chatzy AI REST API for messaging, contact conversations, and agent
    interactions.
  contact:
    name: Chatzy
    url: https://chatzy.ai
    email: support@chatzy.ai
servers:
  - url: https://vevdoh3hve.execute-api.us-east-1.amazonaws.com/prod
    description: Production Server
security: []
tags:
  - name: Authentication
    description: Authentication to access the API
  - name: Contact Conversations
    description: Get contact conversations
  - name: Conversational AI Agent Interactions
    description: Interact with the conversational AI agent
  - name: Authorized iframe Access
    description: APIs for authorized iframe access
paths:
  /ai_agent/refresh_token:
    post:
      tags:
        - Authorized iframe Access
      summary: Get New Access Token from Refresh Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
                - chatbot_id
                - refresh_token
              properties:
                user_id:
                  type: string
                  description: Client's customer ID
                  example: user123
                chatbot_id:
                  type: string
                  format: uuid
                  example: 8a1e3f18-991b-4a2e-9973-f53e7fc94ff1
                refresh_token:
                  type: string
                  description: >-
                    Valid refresh token issued during initial access token
                    generation
                  example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
      responses:
        '200':
          description: New access token issued successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      access_token:
                        type: string
                        description: Newly issued JWT access token
                      expires_at:
                        type: integer
                        description: >-
                          Unix timestamp (ms) when the new access token will
                          expire
                        example: 1753454477000
                    required:
                      - access_token
                      - expires_at

````