Using an API token to authenticate with ActivityInfo
This article explains how you can use an API token to authenticate with ActivityInfo. You can use a token to allow an external system to communicate with ActivityInfo and to access data in your account. An API token, also called an API key, is a long alphanumeric string which is unique and personal to your account.
ActivityInfo password or personal API token?
You can use your ActivityInfo password to let your external system authenticate with ActivityInfo, but we require many users to log into the application using an external identity provider. In this case, you will not have an ActivityInfo password and using an API token is your only option to authenticate with our API.
Even if you have an ActivityInfo password, using an API token to access our API is always the recommended option. It is practical, because API tokens remain functional even when you change your password. But more importantly, it is more secure. This is because
- you can restrict access to your account using a read-only scope,
- you can easily revoke an API token at any time,
- you do not have to share your credentials with anyone or to store them on an external system where they may be exposed to .
In the following sections we explain how you can add and revoke API tokens in your account.
We expect to remove the option to access the ActivityInfo API using your ActivityInfo password sometime in March 2021.
Adding an API token in your account
Your API tokens are listed in your Profile settings.
- Click on the icon with the arrow in the top-right corner to find the link to your profile settings.
- Select the API Tokens menu item in the left-hand menu.
- Click the Add button. This will open the dialog on the right-hand side.
- Provide a label for your token in the Label text field, choose the Scope of your token and then click the Generate button to create a new API token.
After completing the steps above, you will get a message similar to the one in the following screenshot.
At this point, you must copy the API token. You can click on the Copy to clipboard button to do so and paste it where your external system can use it. Once you leave this page, you will no longer be able to see or copy the token!
It is recommended that you use a separate API token for each (external) application and that you carefully label your tokens such that it is easier for you to remember what the token is used for.
Token scope: read-only or read and write?
You have two options for the scope of a token:
- read-only will allow external applications to only read data in your account. The application cannot add, change, or delete records in your databases.
- read & write will allow external applications to not only read your data, but also to modify it by adding, editing, or deleting records.
Note that a token can only limit actions in your account, therefore if you do not have the permission to edit records in a form, then a token with a 'read and write' scope in your account will not allow an external application to edit records either.
Revoking an API token
Revoking a token is the same as deleting it and it is easy to do.
- Open your profile settings and select the API Tokens section in the left-hand menu.
- Find the token you want to revoke and select it.
- Click the Revoke token button in the panel on the right of the screen.
It takes about 5 minutes for the token to be indefinitely removed from our systems after which any application using this token will no longer be able to access the data in your account.
A token which has been revoked can never be restored.