API Authentication

Each request is authenticated using an access token that is associated with an API User. This allows every request to be performed, authorised and audited as that user.

How Authentication Works

Authentication in API v2 consists of three steps:

1. Create an API User.

2. Generate an access token for the API User.

3. Include the access token in the Authorization header of every API request.

The access token identifies the API User performing the request. All actions carried out through the API are recorded as being performed by that user.

API Users

API Users are a dedicated user type designed for system-to-system integrations.

Each API User must be assigned an API Role, which defines the permissions available to that user when accessing the API. The user's access to API resources and operations is determined by the permissions assigned to the API Role.

To learn more about API Roles and permissions, see this article.

Create API Users

API Users are created and managed in the same way as regular users. When creating a new user, select the API User option to designate the user for API access.

Keep the following in mind:

• Once a user has been created, the API User setting cannot be changed. A regular user cannot be converted into an API User, and an API User cannot be converted into a regular user.

• API Users cannot sign in to the eBECAS/EDMISS web interface. They are intended exclusively for system-to-system integrations.

• Like regular users, API Users require a username, first name, last name, and email address. If the user will not send or receive emails through an integration, the email address does not need to be a real or monitored email account.

For instructions on creating and managing API Users, see the Create and Edit Users article.

API Tokens

API tokens are used to authenticate requests to the eBECAS/EDMISS API.

Each API token belongs to an API user. When an integration sends a request, the token identifies which API user is making the request. The API user’s permissions then determine what the integration can access or update.

For security, each integration should use its own API user and token. This makes it easier to control access, review activity, and disable one integration without affecting others.

API tokens should be stored securely and only shared with the system or integration that needs to use them.

API Tokens Status

API Tokens can have the following statuses

API tokens cannot be deleted. If you no longer require a token or need to prevent it from being used, revoke it instead.

API Token Lifetime

For security reasons, all API tokens have a lifetime of one year from the date they are issued.

Once a token expires, it can no longer be used to authenticate API requests. A new API token must be generated and configured in the calling application before it can continue accessing the API.

We recommend replacing API tokens before they expire to avoid interruptions to your integrations.

View API Tokens

To view the tokens and their current status:

1. From the Utilities menu, go to Apps.

2. Locate the Equator API app and click View. If the app is not available, contact your system administrator.

3. Open the Version 2 tab.

4. In the API v2 Tokens section, you can view all API tokens issued for your organisation, including their status, expiry date, and other details.

Create API Tokens

1. From the Utilities menu, go to Apps.

2. Locate the Equator API app and click View. If the app is not available, contact your system administrator.

3. Open the Version 2 tab.

4. From the Grid actions panel, click on the ➕icon. The Create API Token window is displayed.

5. Enter a descriptive token name and select the API user that the token will be associated with.

6. Click on Next.

7. A new token will be created and displayed. Copy and store it in a secure location, as you will not be able to view the token again after closing this window.

Revoke API Tokens

When an API token is no longer required, or you believe it may have been compromised, revoke it immediately. Revoking a token permanently prevents it from being used to authenticate API requests.

Once a token has been revoked, it cannot be reactivated. If the integration still requires access, create a new API token and update the integration to use the new token.

To revoke an API token:

1. From the Utilities menu, go to Apps.

2. Locate the Equator API app and click View. If the app is not available, contact your system administrator.

3. Click the Version 2 tab.

4. In the API v2 Tokens section, locate and select the token you want to revoke from the grid.

5. From the grid actions panel, click the Revoke action for the selected token.

6. Confirm that you want to revoke the token.

After the token is revoked, its status changes to Revoked, and any requests authenticated using that token will be rejected with an authentication error.

Include Token in the Authorization Header

Every API request must include a valid access token in the Authorization header using the Bearer authentication scheme.

Authorization: Bearer <your_access_token>

Replace <your_access_token> with the API token generated for your API user.

Example:

GET /api/v2/students HTTP/1.1
Host: example.com
Authorization: Bearer eyJhbGciOi...
Accept: application/json

If the Authorization header is missing, the token is invalid, or the token has expired or been revoked, the API will reject the request with a 401 Unauthorized response.

Authentication Error (401)

Occurs when the client has not successfully authenticated.

Common causes include:

• The Authorization header is missing.

• The access token is invalid.

• The access token has expired.

• The access token has been revoked.

Example response:

HTTP/1.1 401 Unauthorized

Tokens in the Sandbox Environment

API tokens created in a sandbox environment are temporary and should only be used for development and testing.

When sandbox data is refreshed, all existing sandbox API tokens are removed. After a refresh, you must generate a new API token before your integration can make API requests to the sandbox environment.

Production API tokens are not affected by sandbox data refreshes.

Note: Sandbox and production environments use separate API tokens. A token generated in one environment cannot be used in the other.