Skip to main content
All Cadana API requests require authentication via a Bearer token in the Authorization header:
Bash
curl -X GET 'https://dev-api.cadanapay.com/v1/balances' \
  -H 'Authorization: Bearer YOUR_API_KEY'
  • All requests must be made over HTTPS
  • API keys are environment-specific — sandbox keys don’t work in production and vice versa
  • Missing or invalid tokens return 401 Unauthorized

​
Token Types

Cadana offers three token types for different integration scenarios:
Token TypeScopeExpiresUse Case
Org TokenSingle businessNo*Backend integrations for one business
Platform TokenMultiple businessesNo*Multi-tenant platforms serving multiple companies
User TokenSingle user1 hourFrontend and mobile apps
*Can be manually revoked or regenerated at any time.

​
Org Tokens

The default for most integrations. An Org token gives your backend full access to your organization’s resources — persons, users, payrolls, payments, and settings.
Bash
curl -X GET 'https://api.cadanapay.com/v1/persons' \
  -H 'Authorization: Bearer ORG_TOKEN'
Create Org tokens in the Dashboard under Settings → Developers. You can optionally bind tokens to specific IP addresses for added security. Never expose Org tokens in client-side code.

​
Platform Tokens

These tokens are not restricted to a particular organization. They grant access to the primary organization and any additional businesses created. When using a Platform API Key for business specific actions you must include the X-MultiTenantKey header to specify which business you’re accessing:
Bash
curl -X GET 'https://api.cadanapay.com/v1/users' \
  -H 'Authorization: Bearer PLATFORM_TOKEN' \
  -H 'X-MultiTenantKey: {tenantKey}'
The tenant key is returned when you create a business. Omitting it will scope the request to the default platform business.
Platform API access requires special enablement. Contact your account manager to request access.

​
User Tokens

User tokens are scoped to an individual end-user — whether an admin, employee, or contractor. They grant access only to that user’s resources, making them safe for frontend applications (browser or mobile).
  • Valid for 1 hour, after which a new token must be obtained
  • Obtained through Cadana’s built-in authentication or a custom authentication flow (SSO via your own JWT provider)

​
Which Token Do I Need?

ScenarioTokenHeaders
Backend for one businessOrgAuthorization: Bearer {token}
Backend for multiple businessesPlatformAuthorization: Bearer {token} + X-MultiTenantKey: {key}
Frontend / mobile for a userUserAuthorization: Bearer {token}

​
Common Errors

ErrorCauseSolution
401 UnauthorizedMissing or invalid tokenCheck your API key is correct
401 UnauthorizedWrong environmentUse sandbox key with dev-api.cadanapay.com
401 UnauthorizedPlatform token without tenant keyAdd X-MultiTenantKey header
403 ForbiddenInsufficient permissionsCheck your token type and scope

​
Next Steps

Multi-Tenant Setup

Full guide to Platform API integration

Custom Authentication

SSO and custom JWT integration