The Equator API Version 2 provides a secure and consistent way to access and integrate data from eBECAS with external applications and services.
This guide covers the key steps required to get started with the API, from creating an API token to making your first request.
Before You Begin
Before using the Equator API v2, make sure:
-
API access is enabled for your organisation.
-
Your user account has permission to manage Apps, Users and Roles.
-
You understand what data your integration needs to access.
-
Review the API Best Practices article before configuring your integration.
Overview
Access to the Equator API v2 is authenticated using API tokens created for Integration Users.
Each Integration User is assigned a Role, which defines the permissions available to the integration. The API token follows the permissions of the Role assigned to the Integration User.
API Token → Integration User → Role → Permissions
Create an API Role
Roles determine which permissions an Integration User has and, consequently, what the API token can access.
The first step in setting up API access is to create an API Role with the permissions required by your integration. When creating the Role, make sure it is set to API. Otherwise, it will be created as a Web Role.
We recommend granting only the permissions necessary for the integration to perform its intended functions.
Create an API User
Once you have created the API Role, the next step is to create an API User for your integration.
The API User represents the application or service accessing the API and determines which permissions are available to it.
When creating the user:
-
Set the user as an API User.
-
Enter a name that clearly identifies the integration or application.
-
Enter the remaining details for the user. The email address does not need to be an active email account unless the integration requires email functionality, such as sending or receiving emails.
-
Assign the API Role created in the previous step.
-
Save the user.
The API User will have access to the permissions granted through its assigned API Role.
Create an API Token
Once the API User has been created and assigned the appropriate API Role, the next step is to create an API Token.
The token is used by your integration to authenticate requests to the API and operates with the permissions assigned to the API User.
The API token is a long-lived credential and must be stored securely. Do not expose it in source code, client-side applications, logs, or other locations where it could be accessed by unauthorised users.
Review the API Reference
Once your API access is configured, review the API Reference to explore the available endpoints and understand how to interact with the API.
The API Reference provides detailed information about:
-
Available endpoints and operations
-
Request parameters
-
Request and response formats
-
Required permissions
-
Response codes and errors
You can also test API requests directly from the API Reference, making it easier to understand how each endpoint works before implementing it in your integration.
Learn more about the API Reference
Monitor API Usage
Once your integration is running, regularly monitor its API usage to ensure it is operating as expected.
The API Usage page provides visibility into the requests made through your API tokens, helping you identify usage patterns and investigate unexpected activity or errors.
Monitoring API usage can also help you ensure your integration remains within the applicable API limits.
Learn more about Monitoring API Usage