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

# Refresh a Token

> Generate a new token pair based on a refresh token.

Exchanges a `refresh_token` received from the [Issue Token](https://doc.engagexpay.com/api-reference/authentication/issue-a-token.md) endpoint for a new
pair of `access_token` and `refresh_token`

> [!NOTE]
>
> * The TTLs returned from this API are actually the time that the token will expire; i.e. not validity in number of seconds since creation.
> * The timestamps, i.e. TTLs returned from this endpoint are NOT in ISO 8601 format. Rather it is in the format `YYYY-MM-DD HH:MM:SS+00`.


## OpenAPI

````yaml POST /v1/oauth/refresh-token
openapi: 3.1.0
info:
  title: EngageXPay API
  version: 1.0.0
  description: >-
    A simple API specification for EngageXPay, a financial services platform
    that provides a range of banking and payment solutions for businesses and
    individuals. This API allows developers to integrate EngageXPay's services
    into their applications, enabling functionalities such as customer
    management, transaction processing, and access to financial data.
servers:
  - url: https://sandbox.api.engagexpay.com
    description: Sandbox server
  - url: https://api.engagexpay.com
    description: Production server
security: []
tags:
  - name: Authentication
    description: A modified OAuth 2.0 Client Credential Flow
  - name: Customers
    description: Customer management and document upload operations
  - name: Balances
    description: Retrieve wallet balance information
  - name: Catalogue
    description: |
      A set of endpoints to retrieve contextual data to assemble requests
      to EngageXPay's API
  - name: Beneficiaries
    description: Manage beneficiary accounts for payments and transfers
  - name: Transactions
    description: Transaction history and management for beneficiaries
  - name: Virtual Accounts
    description: Create and manage virtual accounts for USD to USDC conversions
  - name: Fees & FX Rates
    description: Retrieve fees and foreign exchange rates
paths:
  /v1/oauth/refresh-token:
    post:
      tags:
        - Authentication
      summary: Refresh a Token
      description: Generate a new token pair based on a refresh token.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - refresh_token
              properties:
                refresh_token:
                  type: string
                  description: >-
                    The refresh_token received from the [Issue a
                    token](https://docs.engagexpay.com/api-reference/authentication/issue-a-token)
                    endpoint.
      responses:
        '200':
          description: Token issued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    TokenResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            access_token:
              type: string
              example: LIZqxTM9NgEgvCSCgwCKCSl4dTVCPAYE59fTOZs6gwvup4TQuD
            access_token_ttl:
              type: string
              example: '2026-09-24 09:26:24+00'
            refresh_token:
              type: string
              example: FEWWXAMXPFSc8uAgDlRXk6zlCxBSKGM6GlAYxRpYwdDRMkiXIm
            refresh_token_ttl:
              type: string
              example: '2026-09-30 09:26:24+00'
            current_time:
              type: string
              example: '2026-09-23 09:26:24+00'
  responses:
    AuthenticationError:
      description: Authentication failed due to invalid credentials
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Authentication failed
    ValidationError:
      description: Failed due to a formatting error.
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
              errors:
                type: array
                items:
                  type: object
                  additionalProperties:
                    type: string

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.