Authentication FYATU API v3 uses JWT (JSON Web Tokens) for secure, stateless authentication. Exchange your app credentials for a short-lived access token, then use that token to authenticate all subsequent requests.
Overview Getting Your Credentials
Open Business Console
Navigate to the Business Console from your dashboard
Select Your App
Click on your Collection App or Issuing App depending on which APIs you need
Get API Keys
Go to Settings tab, then click API Keys & Credentials
App Types & Scopes Your access token’s scopes depend on the app type:
App Type Available APIs Scopes Collection App Collections, Payouts collect:write, collect:read, payout:write, payout:readIssuing App eSIM, Cards, Cardholders esim:write, esim:read, cards:write, cards:read, cardholders:write, cardholders:read
Token Lifecycle Property Value Token Type JWT (HS256) Token Expiry 24 hours Refresh Window Up to 5 minutes after expiry Token Format Bearer token
Step 1: Obtain Access Token Exchange your app credentials for a JWT access token:
curl -X POST https://api.fyatu.com/api/v3/auth/token \ -H "Content-Type: application/json" \ -d '{ "appId": "DD123FR45446CECES", "secretKey": "your_secret_key_here", "grantType": "client_credentials" }'
Response { "success" : true , "status" : 200 , "message" : "Token generated successfully" , "data" : { "accessToken" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJERDEyM0ZSNDQ0NjZDRUNFUyIsImJ1cyI6Ik4xUzBXM1E4UDBWMUU1TTZRNFIzRDhaOSIsInR5cGUiOiJjb2xsZWN0aW9uIiwic2NvcGVzIjpbImNvbGxlY3Q6d3JpdGUiLCJjb2xsZWN0OnJlYWQiLCJwYXlvdXQ6d3JpdGUiLCJwYXlvdXQ6cmVhZCJdLCJpYXQiOjE3MzYwNzU4MDAsImV4cCI6MTczNjE2MjIwMCwianRpIjoiand0XzdhZjRkMmI4ZTkxYzM1ZmE0YjIxODkwZSJ9.x2kPqR7mN5vL8wT3fA9sD6gH1jK4cB0eW7yU2iO3pVn" , "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_7af4d2b8e91c35fa4b21890e" , "timestamp" : "2026-01-05T10:30:00+00:00" } }
Step 2: Use Token in Requests Include the access token in the Authorization header for all API requests:
curl -X GET https://api.fyatu.com/api/v3/collections \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Step 3: Refresh Token (Optional) Before your token expires, you can refresh it to get a new token. Refresh is allowed up to 5 minutes after expiry.
curl -X POST https://api.fyatu.com/api/v3/auth/refresh \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Response { "success" : true , "status" : 200 , "message" : "Token refreshed successfully" , "data" : { "accessToken" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJERDEyM0ZSNDQ0NjZDRUNFUyIsImJ1cyI6Ik4xUzBXM1E4UDBWMUU1TTZRNFIzRDhaOSIsInR5cGUiOiJjb2xsZWN0aW9uIiwic2NvcGVzIjpbImNvbGxlY3Q6d3JpdGUiLCJjb2xsZWN0OnJlYWQiLCJwYXlvdXQ6d3JpdGUiLCJwYXlvdXQ6cmVhZCJdLCJpYXQiOjE3MzYxNjIyMDAsImV4cCI6MTczNjI0ODYwMCwianRpIjoiand0XzhjZTk1YTRmMWIzZDY3ZWEyYzA5NDU4ZiJ9.m8nK3pW6rY1qL5vJ0hS9dF2gB4eA7xC3wU8tZ0iV5oR" , "tokenType" : "Bearer" , "expiresIn" : 86400 , "expiresAt" : "2026-01-07T10:30:00+00:00" , "appType" : "collection" , "scopes" : [ "collect:write" , "collect:read" , "payout:write" , "payout:read" ] }, "meta" : { "requestId" : "req_8ce95a4f1b3d67ea2c09458f" , "timestamp" : "2026-01-06T10:30:00+00:00" } }
Error Responses Invalid Credentials { "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" } }
Token Expired { "success" : false , "status" : 401 , "message" : "Invalid or expired token" , "error" : { "code" : "AUTH_TOKEN_INVALID" }, "meta" : { "requestId" : "req_abc123def456" , "timestamp" : "2026-01-05T10:30:00+00:00" } }
Insufficient Scope { "success" : false , "status" : 403 , "message" : "Access denied. Required scope: esim:write" , "error" : { "code" : "AUTH_SCOPE_DENIED" }, "meta" : { "requestId" : "req_abc123def456" , "timestamp" : "2026-01-05T10:30:00+00:00" } }
JWT Payload Structure When decoded, the JWT token contains:
{ "sub" : "DD123FR45446CECES" , "bus" : "BUS_xxxxxxxxxxxx" , "type" : "collection" , "scopes" : [ "collect:write" , "collect:read" , "payout:write" , "payout:read" ], "iat" : 1704451800 , "exp" : 1704455400 , "jti" : "jwt_xxxxxxxxxxxxxxxxxxxx" }
Claim Description subApp ID (subject) busBusiness ID typeApp type (collection or issuing) scopesArray of granted permissions iatIssued at timestamp expExpiration timestamp jtiUnique token identifier
Best Practices
Store tokens securely in memory or encrypted storage
Never expose tokens in client-side code or logs
Implement automatic token refresh before expiry
Check token expiry before each request
Refresh when less than 5 minutes remain
Handle refresh failures by re-authenticating
Catch 401 errors and re-authenticate
Catch 403 errors and check required scopes
Log request IDs for debugging with FYATU support
Rate Limits Authentication endpoints have the following rate limits:
Endpoint Rate Limit POST /v3/auth/token10 requests per minute POST /v3/auth/refresh30 requests per minute
Exceeding rate limits will result in a 429 Too Many Requests response. Implement exponential backoff in your retry logic.
