Authentication

FluxiQ Core uses JWT (JSON Web Token) authentication for API access. All API requests must include a valid access token in the Authorization header.

Overview

Method	Use Case	Token Lifetime
API Key	Server-to-server (merchants)	No expiry (revocable)
JWT	User sessions (banking, admin)	15 minutes (access) + 7 days (refresh)

API Key Authentication

For merchant integrations, use API keys:

GET /api/v1/accounts
Authorization: Bearer sk_live_abc123def456
Content-Type: application/json

Generate API Key

POST /api/v1/merchants/{merchant_id}/api-keys
Authorization: Bearer {admin_jwt_token}
Content-Type: application/json

{
  "name": "Production Key",
  "permissions": ["accounts:read", "pix:write", "transfers:write"]
}

Response:

{
  "data": {
    "id": "key_01HQGX...",
    "name": "Production Key",
    "key": "sk_live_abc123def456ghi789",
    "permissions": ["accounts:read", "pix:write", "transfers:write"],
    "created_at": "2026-02-03T12:00:00Z"
  }
}

WARNING

The full API key is only shown once at creation time. Store it securely.

JWT Authentication

For user-facing applications (banking UI, admin console):

Login

POST /api/v1/auth/login
Content-Type: application/json

{
  "document": "12345678901",
  "password": "your-password"
}

Response:

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 900
  }
}

Using the Token

GET /api/v1/accounts
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

Refresh Token

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Logout

POST /api/v1/auth/logout
Authorization: Bearer {access_token}

Permissions (RBAC)

Role	Description	Permissions
owner	Full access to all resources	*
manager	Manage accounts, view transactions	accounts:*, transactions:read, pix:*
operator	Execute transactions, view accounts	accounts:read, transactions:read, pix:write

Permission Scopes

Scope	Description
accounts:read	View account balances and details
accounts:write	Create and update accounts
pix:read	View PIX transactions
pix:write	Send and receive PIX payments
transfers:read	View internal transfers
transfers:write	Execute internal transfers
webhooks:read	View webhook configurations
webhooks:write	Create and manage webhooks
users:read	View user profiles
users:write	Manage user accounts

Rate Limiting

Method	Limit	Window
API Key	1,000 req/min	Per key
JWT	100 req/min	Per user
Unauthenticated	10 req/min	Per IP

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1706961600

Error Responses

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired authentication token"
  }
}

403 Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions for this operation",
    "required_permission": "pix:write"
  }
}

429 Too Many Requests

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 30 seconds",
    "retry_after": 30
  }
}