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

# Generate Token

> Generate a JWT access token for Fyatu API v3.20. POST /auth/token with your businessId, secretKey, and requested scopes.

> [!NOTE]
>
> **Getting Your Credentials:** Login to [FYATU Dashboard](https://web.fyatu.com) → Business Dashboard → Developer → API Credentials

## Overview

Exchange your API credentials (`businessId` and `secretKey`) for a JWT access token. This token authenticates all V3.20 API requests. Specify only the scopes your integration needs.

## Token Details

| Property | Value |
| - | - |
| Algorithm | JWT HS256 |
| Expiry | 24 hours (86400 seconds) |
| Refresh window | Up to 5 minutes after expiry |

## Available Scopes

| Scope | Description |
| - | - |
| `cards:read` | View cards and card transactions |
| `cards:write` | Create, fund, freeze, replace, delete cards |
| `cardholders:read` | View cardholder profiles |
| `cardholders:write` | Create, update, delete cardholders; initiate KYC |
| `programs:read` | View card programs and products |
| `account:read` | View wallet, transactions, pricing, statement |
| `webhooks:read` | View webhook configuration and event types |
| `webhooks:write` | Update webhook URL, regenerate secret, send test |

## Using the Token

Include the token in the `Authorization` header for all protected requests:

```bash theme={null}
curl -X GET https://api.fyatu.com/api/v3.20/cardholders \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
```

## Error Codes

| Code | Description |
| - | - |
| `VALIDATION_ERROR` | Missing or invalid request parameters |
| `AUTH_INVALID_CREDENTIALS` | Business not found or secret key mismatch |
| `AUTH_BUSINESS_INACTIVE` | Business account is suspended or inactive |

> [!TIP]
>
> Request only the scopes your integration needs. A read-only reporting tool should only request `*:read` scopes — this limits the impact if the token is ever compromised.


## OpenAPI

````yaml v3.20/openapi.json POST /auth/token
openapi: 3.1.0
info:
  title: FYATU API v3
  description: >-
    FYATU API v3 with JWT authentication for Collections, Payouts, and Card
    Issuing.
  version: 3.0.0
  contact:
    name: FYATU Support
    url: https://fyatu.com
    email: support@fyatu.com
servers:
  - url: https://api.fyatu.com/api/v3
    description: Production
security: []
tags:
  - name: Authentication
    description: JWT token management endpoints
  - name: Account
    description: Business account, wallet, and address management
  - name: Collections
    description: Accept payments from customers via checkout sessions
  - name: Refunds
    description: Issue refunds for completed collections
  - name: Payouts
    description: Send money to Fyatu account holders
  - name: Cardholders
    description: Cardholder management for card issuing programs
  - name: Cards
    description: Issue, fund, freeze, and manage virtual cards
  - name: Webhooks
    description: Webhook configuration and management
paths:
  /auth/token:
    post:
      tags:
        - Authentication
      summary: Generate Access Token
      description: >-
        Exchange app credentials (appId and secretKey) for a JWT access token.
        The token expires in 24 hours and can be refreshed within 5 minutes
        after expiry.
      operationId: generateToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
            example:
              appId: A1B2C3D4E5F6G7H8
              secretKey: your_secret_key_here
              grantType: client_credentials
      responses:
        '200':
          description: Token generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
              example:
                success: true
                status: 200
                message: Token generated successfully
                data:
                  accessToken: >-
                    eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJBMUIyQzNENEU1RjZHN0g4IiwiYnVzIjoiTjFTMFczUThQMFYxRTVNNlE0UjNEOFo5IiwidHlwZSI6ImNvbGxlY3Rpb24iLCJzY29wZXMiOlsiY29sbGVjdDp3cml0ZSIsImNvbGxlY3Q6cmVhZCIsInBheW91dDp3cml0ZSIsInBheW91dDpyZWFkIl0sImlhdCI6MTczNjA3NTgwMCwiZXhwIjoxNzM2MTYyMjAwLCJqdGkiOiJqd3RfOWYzZTJhMWI0YzVkNjdlOCJ9.xK2pM7nV3wL8qR5tY0sF4gH9jB6eA1cD3uW2iZ8vX0mN
                  tokenType: Bearer
                  expiresIn: 86400
                  expiresAt: '2026-01-06T10:30:00+00:00'
                  appType: collection
                  scopes:
                    - collect:write
                    - collect:read
                    - payout:write
                    - payout:read
                meta:
                  requestId: req_9f3e2a1b4c5d67e8
                  timestamp: '2026-01-05T10:30:00+00:00'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                status: 400
                message: Validation failed
                error:
                  code: VALIDATION_ERROR
                  details:
                    - field: appId
                      message: AppId is required
                meta:
                  requestId: req_abc123def456
                  timestamp: '2026-01-05T10:30:00+00:00'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                status: 401
                message: Invalid credentials. Secret key mismatch.
                error:
                  code: AUTH_INVALID_CREDENTIALS
                meta:
                  requestId: req_abc123def456
                  timestamp: '2026-01-05T10:30:00+00:00'
components:
  schemas:
    TokenRequest:
      type: object
      required:
        - appId
        - secretKey
        - grantType
      properties:
        appId:
          type: string
          description: Your app ID (16 characters)
          example: DD123FR45446CECES
          minLength: 8
        secretKey:
          type: string
          description: Your app secret key
          example: your_secret_key_here
          minLength: 16
        grantType:
          type: string
          enum:
            - client_credentials
          default: client_credentials
          description: OAuth grant type (must be 'client_credentials')
          example: client_credentials
    TokenResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status:
          type: integer
          example: 200
        message:
          type: string
          example: Token generated successfully
        data:
          $ref: '#/components/schemas/TokenData'
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        status:
          type: integer
          example: 401
        message:
          type: string
          example: Invalid credentials
        error:
          $ref: '#/components/schemas/Error'
        meta:
          $ref: '#/components/schemas/Meta'
    TokenData:
      type: object
      properties:
        accessToken:
          type: string
          description: JWT access token to use in Authorization header
        tokenType:
          type: string
          enum:
            - Bearer
          description: Token type (always Bearer)
        expiresIn:
          type: integer
          description: Token lifetime in seconds
          example: 86400
        expiresAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when token expires
        appType:
          type: string
          enum:
            - collection
            - issuing
          description: App type determining available APIs
        scopes:
          type: array
          items:
            type: string
          description: Permissions granted to this token
          example:
            - collect:write
            - collect:read
            - payout:write
            - payout:read
    Meta:
      type: object
      properties:
        requestId:
          type: string
          description: Unique request ID for tracking
          example: req_abc123def456
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the response
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code for programmatic handling
          example: AUTH_INVALID_CREDENTIALS
        details:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
          description: Validation error details (for VALIDATION_ERROR)
    ValidationError:
      type: object
      properties:
        field:
          type: string
          description: Field that failed validation
          example: appId
        message:
          type: string
          description: Validation error message
          example: AppId is required

````

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