API Tokens
API tokens provide a secure method for accessing Ocamba’s platform APIs. This document explains the creation, management, and best practices for using API tokens.
API Tokens can be accessed via the Profile menu by selecting the 'API Tokens' field. The Profile menu is available in the top-right corner of the platform interface, as shown in the screenshot above.
What are API Tokens?
API tokens are unique alphanumeric keys that grant applications access to specific Ocamba APIs. They are essential for automation and third-party integrations.
Features of API Tokens
- Granular Access: Define specific validity periods for each token.
- Flexibility: Enable rolling keys without affecting functionality.
- Ease of Management: Use the Ocamba UI to create, edit, or delete tokens.
How to Create API Tokens
- Navigate to the API Tokens section in your profile.
- Click Add Token and complete the configuration.
Adding a Token: Validity Defaults
When a user creates a new API token using the Add Token option:
Token Name:
The token name is required to uniquely identify the token. If a name is not provided, the system will not allow the token to be created.
Validity Period:
Valid From: If the user does not specify a start date, the token will default to “Immediately”, meaning it becomes active as soon as it is created.
Valid Until: If the user does not specify an end date, the token will default to “Never”, meaning the token will remain active indefinitely unless manually deleted.
In the example above "example 2" API Token has been added without specified validity date range while "example token" has been added with specified date range validity period.
- Custom Date Range: If the user specifies both the Valid From and Valid Until dates, the token will be active only within the specified time range.
Behavior Summary:
If no dates are specified: The token is valid immediately and never expires.
If dates are specified: The token follows the defined start and end dates.
This behavior is designed to provide maximum flexibility for users while ensuring convenience for quick token generation.
Viewing the Token After Creation
Once an API token is created, the user is redirected to a confirmation screen displaying the newly generated token and its details:
Token Key:
The newly created API token is displayed in a secure field.
Newly Created API Token
CURL Command: A pre-generated CURL command is provided to test the token’s validity. This allows users to confirm that the token is functioning correctly in their integrations.
Action Buttons: View all API Tokens: Redirects the user back to the list of all API tokens for further management.
Managing Lost API Tokens
If an API token is lost, users have two options to recover or replace it:
Roll the Token:
Use the Roll option to generate a new key for the same token.
Rolling a token retains its original validity period and configuration.
The old token key will immediately become invalid, and the new key must be updated in all connected integrations.
Delete and Create a New Token:
If preferred, the lost token can be deleted, and a new token can be created from scratch.