Authentication

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 Type	Scope	Expires	Use Case
Org Token	Single business	No*	Backend integrations for one business
Platform Token	Multiple businesses	No*	Multi-tenant platforms serving multiple companies
User Token	Single user	1 hour	Frontend 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?

Scenario	Token	Headers
Backend for one business	Org	`Authorization: Bearer {token}`
Backend for multiple businesses	Platform	`Authorization: Bearer {token}` + `X-MultiTenantKey: {key}`
Frontend / mobile for a user	User	`Authorization: Bearer {token}`

Verify Your Token

GET /v1/me returns the calling key’s access level and the business the request resolved to, including its businessId and tenant key:

Bash

curl -X GET 'https://api.cadanapay.com/v1/me' \
  -H 'Authorization: Bearer YOUR_API_KEY'

With a Platform token, include X-MultiTenantKey and the response shows which sub-business your requests operate on — useful for confirming tenant scoping before making changes.

Common Errors

Error	Cause	Solution
`401 Unauthorized`	Missing or invalid token	Check your API key is correct
`401 Unauthorized`	Wrong environment	Use sandbox key with `dev-api.cadanapay.com`
`403 Forbidden`	Tenant key doesn’t belong to your platform	Verify the tenant key matches a business you created
`403 Forbidden`	Insufficient permissions	Check your token type and scope

Get Started

Workforce Management

Payroll & Compliance

White-Label UI

Platform Integration

Payments

Wallets

Token Types

Org Tokens

Platform Tokens

User Tokens

Which Token Do I Need?

Verify Your Token

Common Errors

Next Steps

Multi-Tenant Setup

Custom Authentication

​Token Types

​Org Tokens

​Platform Tokens

​User Tokens

​Which Token Do I Need?

​Verify Your Token

​Common Errors

​Next Steps

Multi-Tenant Setup

Custom Authentication

Token Types

Org Tokens

Platform Tokens

User Tokens

Which Token Do I Need?

Verify Your Token

Common Errors

Next Steps