> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cadanapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, token types, and how to authenticate requests

All Cadana API requests require authentication via a Bearer token in the `Authorization` header:

```bash Bash theme={null}
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 Bash theme={null}
curl -X GET 'https://api.cadanapay.com/v1/persons' \
  -H 'Authorization: Bearer ORG_TOKEN'
```

Create Org tokens in the [Dashboard](https://app.cadanapay.com) 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 Bash theme={null}
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](/api-reference/workforce/platform/create). Omitting it will scope the request to the default platform business.

<Warning>
  Platform API access requires special enablement. Contact your account manager to request access.
</Warning>

### 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](/white-label/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}`                             |

***

## 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                      |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Multi-Tenant Setup" icon="building" href="/platform/multi-tenant-setup">
    Full guide to Platform API integration
  </Card>

  <Card title="Custom Authentication" icon="fingerprint" href="/white-label/custom-authentication">
    SSO and custom JWT integration
  </Card>
</CardGroup>