Authentication

FWallet uses header-based API key authentication. There are two authentication modes, each for a different level of access.

Authentication Modes

X-API-Key — Tenant-Scoped

Used for all tenant-scoped operations: managing wallets, creating transfers, processing deposits, querying ledger entries, and tenant administration.

curl https://api.fwallet.co.ug/v1/wallets \
  -H "X-API-Key: fwk_test_a1b2c3d4e5f6..."

The API key determines which tenant the request belongs to. You never pass a tenant_id in the URL or body — it is derived from the key. This means a key can only access data belonging to its tenant.

X-System-Key — Platform-Level

Used for platform administration: creating tenants, provisioning API keys, and accessing system-wide endpoints under /v1/system/*.

curl https://api.fwallet.co.ug/v1/tenants \
  -H "X-System-Key: $SYSTEM_KEY"

The system key is configured at the platform level (environment variable) and is not tenant-scoped.

Provisioning API Keys

API keys are created via the system endpoint:

curl -X POST https://api.fwallet.co.ug/v1/tenants/tn_01JQHXYZ.../api-keys \
  -H "Content-Type: application/json" \
  -H "X-System-Key: $SYSTEM_KEY" \
  -d '{
    "name": "Production Key",
    "scopes": [
      "ledger:read",
      "ledger:write",
      "wallet:transfer",
      "wallet:deposit",
      "tenant:manage"
    ],
    "environment": "test"
  }'

Response:

{
  "id": "ak_01JQHXYZ...",
  "name": "Production Key",
  "key": "fwk_test_a1b2c3d4e5f6g7h8i9j0...",
  "scopes": [
    "ledger:read",
    "ledger:write",
    "wallet:transfer",
    "wallet:deposit",
    "tenant:manage"
  ],
  "environment": "test",
  "createdAt": "2026-03-18T10:00:01.000Z"
}

Caution

The key field is returned only once, at creation time. It is not stored in plain text and cannot be retrieved later. Store it securely immediately after creation.

Key Format

API keys follow a predictable prefix format:

fwk_{environment}_{random}

• fwk_test_... — test environment key
• fwk_live_... — live environment key

The prefix makes it easy to identify the environment a key belongs to and to detect accidental use of test keys in production (or vice versa).

Scopes

Each API key has a set of scopes that control what operations it can perform:

Scope	Permits
ledger:read	Read journal entries and journal lines. Query account balances and transaction history.
ledger:write	Post journal entries (typically internal; most entries are created by transfers/deposits).
wallet:transfer	Create transfers between wallets.
wallet:deposit	Process deposits (MoMo webhooks, bank slip verification).
tenant:manage	Manage tenant settings, fee schedules, approval policies, and view tenant-level reports.

Principle of Least Privilege

Create keys with only the scopes they need:

• A mobile money integration needs only wallet:deposit
• A reporting dashboard needs only ledger:read
• A transfer service needs wallet:transfer and ledger:read
• A full admin key needs all scopes

# Key for a read-only reporting service
curl -X POST https://api.fwallet.co.ug/v1/tenants/tn_01JQHXYZ.../api-keys \
  -H "Content-Type: application/json" \
  -H "X-System-Key: $SYSTEM_KEY" \
  -d '{
    "name": "Reporting Dashboard",
    "scopes": ["ledger:read"],
    "environment": "live"
  }'

Response:

{
  "id": "ak_02ABCDEF...",
  "name": "Reporting Dashboard",
  "key": "fwk_live_x9y8z7w6v5u4...",
  "scopes": ["ledger:read"],
  "environment": "live",
  "createdAt": "2026-03-18T10:00:02.000Z"
}

If a key attempts an operation outside its scopes, the API returns 403 Forbidden:

{
  "error": "forbidden",
  "message": "API key does not have the required scope: wallet:transfer"
}

Environments

API keys are created in one of two environments:

Environment	Purpose
test	Development and testing. May have relaxed validation, simulated provider webhooks.
live	Production. Full validation, real provider integrations.

The environment is set at key creation time and cannot be changed. This prevents accidental use of test infrastructure in production.

Endpoint Authentication Summary

Endpoint Pattern	Required Header	Description
POST /v1/tenants	X-System-Key	Create a new tenant
POST /v1/tenants/{id}/api-keys	X-System-Key	Provision an API key for a tenant
/v1/system/*	X-System-Key	Platform administration endpoints
/v1/wallets/*	X-API-Key	Wallet operations
/v1/transfers/*	X-API-Key	Transfer operations
/v1/deposits/*	X-API-Key	Deposit operations
/v1/journal-entries/*	X-API-Key	Ledger queries
/v1/admin/*	X-API-Key (with tenant:manage)	Tenant admin operations

Error Responses

Status	Meaning
401 Unauthorized	Missing or invalid API key / system key
403 Forbidden	Valid key, but insufficient scopes for the requested operation

{
  "error": "unauthorized",
  "message": "Missing or invalid X-API-Key header"
}