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_your_secret_key_here'

API keys are prefixed with sk_ (secret key). Keep your key secure — do not expose it in client-side code, public repositories, or 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."
  }
}

403 Forbidden

Returned when the API key is valid but doesn’t have permission for the requested resource:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Access denied."
  }
}

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_your_secret_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.

QR API

Onboarding API

Terminal Gateway

Transaction Reporting API

Ecom API

Shared Resources

API Key Authentication

Entity Scoping

Error Responses

401 Unauthorized

403 Forbidden

Security Best Practices

What’s Next?

Quickstart

Filtering & Sorting

​API Key Authentication

​Entity Scoping

​Error Responses

​401 Unauthorized

​403 Forbidden

​Security Best Practices

​What’s Next?

Quickstart

Filtering & Sorting

API Key Authentication

Entity Scoping

Error Responses

401 Unauthorized

403 Forbidden

Security Best Practices

What’s Next?