API Reference

Authentication

Overview

To use the Cadana API, you'll need an API key to authenticate your requests. You can generate, view, and manage your API keys in the Cadana Dashboard.

Authentication is done via Bearer Token. Include your API key in the authorization header of the request you send from your backend server. All requests to the Cadana API must be made over HTTPS. Requests made over unsecure HTTP and those without the proper authorization header will fail.

To ensure that your API key is set up correctly, you can make a test request to one of Cadana's read endpoints. If set up correctly, you should receive a successful response. If there's an issue with your authentication, you'll receive an error message detailing the problem.

curl -X GET 'https://api.cadanapay.com/v1/users'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer YOUR_API_KEY'

Types of API Tokens

OAuth 2.0 Bearer Token

Cadana’s API leverages the OAuth 2.0 Bearer Token mechanism for authentication. It's essential that every API call you make includes this bearer token in the header for successful authentication.

Token Types

Cadana offers three distinct types of API tokens to cater to various integration scenarios:

Org API Tokens

  • Purpose: These are broad, system-level tokens, granting access to a specific organization and all its associated functionalities.
  • Usage: Ideal for backend infrastructure, these tokens should never be exposed to end-users.
  • Creation & Management: Generate or revoke these tokens via Cadana’s Dashboard. For added security, you can bind tokens to specific IP addresses.

Platform API Tokens

  • Purpose: These tokens are not restricted to a particular organization. They grant access to the primary organization and any additional businesses created.
  • Access: Platform API tokens require special access before they can be created. Please reach out to your account manager to enable access.
  • Special Feature: When using a Platform API Key, for business specific actions, you must pass the custom header X-MultiTenantKey to specify which business you're accessing. For instance:

curl -X GET 'https://api.cadanapay.com/v1/users'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ${PLATFORM_TOKEN}'
-H 'X-MultiTenantKey: ${tenantKey}'

User Tokens

  • Purpose: User Tokens are specific to individual end-users, whether they are an admin, employee, or contractor. They grant access solely to resources associated with the particular user for whom the token was generated.

  • Duration: A User Token remains valid for up to 1 hour. After this period, you'll need to obtain a new token.

  • Usage: These tokens are designed for making direct API calls from your frontend, be it a browser or a mobile app. To enhance user experience and minimize the frequency of authentications, it's recommended to store the user token on the user’s device. The browser's local storage is an ideal location for this.