Authentication

API Key Authentication

All requests require an API key passed in the X-API-Key header:

curl 'https://api.sbx.moduluslabs.io/reports/v1/transactions' \
  -H 'X-API-Key: sk_test_your_api_key_here'

Newer credentials can use sk_test_, pk_test_, sk_live_, or pk_live_. Some legacy Modulus APIs use the shorter sk_ or pk_ prefixes. Always send the complete key exactly as issued. Permissions determine access independently of the prefix. Keep any key that can read transaction data out of client-side code, public repositories, and browser requests.

Requests without a valid API key receive a 401 Unauthorized response.

Entity Scoping

Every API key is associated with an entity level in the hierarchy: Partner, Merchant, or Branch. Data access is automatically restricted based on your key’s level.

Partner
├── Merchant A
│   ├── Branch 1  →  sees Branch 1 transactions only
│   └── Branch 2  →  sees Branch 2 transactions only
│   └── (Merchant A key sees all branches)
└── Merchant B
    └── Branch 3
    └── (Partner key sees everything)

Key Level	Transactions	Merchants	Branches
Partner	All merchants and branches	All merchants	All branches
Merchant	Own branches only	Own merchant only	Own branches only
Branch	Own transactions only	Parent merchant only	Own branch only

Entity scoping is applied automatically - you don’t need to add any special filters. A merchant-level key will never see another merchant’s data, even if you try to filter by their merchant_id.

Error Responses

401 Unauthorized

Returned when the API key is missing, invalid, or expired:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key."
  }
}

503 Service Unavailable

Returned when the service is temporarily unavailable. This is not an invalid-credential response; retry with backoff and keep the same key.

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable."
  }
}

Security Best Practices

Keep keys server-side

Never include API keys in frontend code, mobile apps, or public repositories. Make API calls from your backend server.

Use environment variables

Store API keys in environment variables, not in source code:

export MODULUS_API_KEY=sk_test_your_api_key_here

Rotate keys regularly

Contact support@moduluslabs.io to rotate your API key if you suspect it has been compromised.

Use the minimum scope

Request a merchant-level or branch-level key if you don’t need partner-wide access. Least privilege reduces the impact of key exposure.

Get Started

QR API

Webhooks API

Onboarding API

Terminal Gateway API

Transaction Reporting API

Ecom API

Shared Resources

API Key Authentication

Entity Scoping

Error Responses

401 Unauthorized

503 Service Unavailable

Security Best Practices

What’s Next?

Quickstart

Filtering & Sorting

​API Key Authentication

​Entity Scoping

​Error Responses

​401 Unauthorized

​503 Service Unavailable

​Security Best Practices

​What’s Next?

Quickstart

Filtering & Sorting

API Key Authentication

Entity Scoping

Error Responses

401 Unauthorized

503 Service Unavailable

Security Best Practices

What’s Next?