> ## 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 using client credentials. POST /auth/token with appId and secretKey.
**Getting Your Credentials:** Login to [FYATU Dashboard](https://web.fyatu.com) → Business Console → Select App → Settings → API Keys & Credentials
## Overview
Exchange your app credentials (`appId` and `secretKey`) for a JWT access token. This token is required to authenticate all other V3 API requests.
## Token Details
| Property | Value |
| -------------- | ---------------------------- |
| Token Type | JWT (HS256) |
| Expiry | 24 hours (86400 seconds) |
| Refresh Window | Up to 5 minutes after expiry |
## Scopes by App Type
| Scope | Description |
| --------------- | ------------------------------------------ |
| `collect:write` | Create checkout sessions, process payments |
| `collect:read` | View collection transactions |
| `payout:write` | Send payouts |
| `payout:read` | View payout transactions |
| Scope | Description |
| ------------------- | ---------------------------------- |
| `cards:write` | Create cards, fund, freeze |
| `cards:read` | View card details and transactions |
| `cardholders:write` | Create and update cardholders |
| `cardholders:read` | View cardholder details |
## Using the Token
Once you have an access token, include it in the `Authorization` header for all API requests:
```bash theme={null}
curl -X GET https://api.fyatu.com/api/v3/collections \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```
## Error Codes
| Code | Description |
| -------------------------- | ------------------------------------- |
| `VALIDATION_ERROR` | Missing or invalid request parameters |
| `AUTH_INVALID_CREDENTIALS` | App not found or secret key mismatch |
| `AUTH_APP_INACTIVE` | App is suspended or archived |
Store tokens securely and track the `expiresAt` timestamp. Refresh tokens proactively before they expire to ensure uninterrupted API access.
## OpenAPI
````yaml v3/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
````