Generate API tokens

Tokens are required to access the integrator.io API. Account owners and administrators can use the integrator.io API to perform add/edit/delete operations on any resource in their account. Only these two roles can view the API tokens page.

Contents

• Generate an API token
  • Create API token – General settings
  • Create API token – Token permissions
• Manage and retrieve the API token
• Common questions
  • Why am I getting token email notifications?
  • Why is the API key in plain text?
  • Is the API key committed to any source code repository?
  • Why can't API keys use ENV variables or a secret management system where keys are not exposed in plain text?
  • Why does the API key require full access and not read only?
  • Why did we not get this alert in the test environment and only in the production environment?
  • Is the API key protected behind a secure login or are these workflows available widely?
  • Do we have any audit mechanism to who is logging in to the accounts that have access to the key?

Generate an API token

An API token provides authentication to integrator.io from the third-party endpoint, so that you can access the resources that you specify. An account owner or administrator can create an API token that applies to an account or an Integration App, as follows:

Create the token in one of the following ways:

• Common to your integrator.io account – Open API tokens from the Resources menu. Click + Create API token at the top right.
• Specific to an Integration App – In the Integration App’s dashboard, open the Admin tab, click the API tokens setting. Click + Create API token at the top right.

Note: Tokens are only visible to account owners or admins.

Enter the General settings and Token permissions, and save the API token, then copy the token for use in the calling app.

Create API token – General settings

Name (required): Provide a meaningful name to distinguish it from other tokens in the list.

Description (optional): Enter any identifying characteristics of this API token item.

Auto purge token (required): Select the time after which the token should be automatically purged from the system.

Note: If you are unable to generate long-lived API tokens (tokens with expiration limits beyond one hour), you must add an API Management license to your account. This license allows you to create tokens that are valid for longer than one hour. API Management is included in Enterprise plans and is available for purchase in Standard, Professional, and Premium plans.

Create API token – Token permissions

Scope (required): Set the access permissions for your token:

• Full access – tokens provisioned at the account level have unrestricted permissions to your integrator.io account. No further scopes need to be selected.
• Custom – tokens can be created with only minimal permissions to specific resources in your integrator.io account, and they can only be used to invoke very specific integrator.io APIs. Multiple selections are allowed for the custom scopes chosen below.

Connections (enabled for custom scopes, optional): Select the connections that this token will be able to access.

Exports (enabled for custom scopes, optional): Select the exports that this token will be able to access.

Imports (enabled for custom scopes, optional): Select the imports that this token will be able to access.

My APIs (enabled for custom scopes, optional): Select the My APIs that this token will be able to access. 

Save or Save & close (required): Click to save your new token.

Manage and retrieve the API token

You can manage your tokens in the API tokens page or the Integration App’s Admin tab; several options are available under Action:

• Edit API token
• View audit log
• Revoke API token
• Generate new API token

To copy the token, click Show token and select the copy button (  ).

Common questions

Why am I getting token email notifications?

If you're the account owner or administrator, you'll receive an email alert notification every time a token is created, accessed, modified, or if a token is viewed in plain text (to expose the actual token) to inform you of the activity. This is a security measure, to make you aware of any activity involving these tokens.

If you suspect that your account password has been compromised, click the user avatar icon > My account. In the My account page, click the pencil icon next to Password to specify a new password.

Note that the actual token is never revealed in the email or via the user interface, unless the user with access permissions actively clicks to view the token. 

Why is the API key in plain text?

Only owners and administrators can view these tokens in plain text. If an owner or an administrator clicks the view token button, an email notification is sent to the account owner.

Is the API key committed to any source code repository?

Tokens are securely generated and are unique to each customer’s account and token instance. The keys are safely secured in a database and are not stored in any code repository. The same security measures for storing credentials are used for API key encryption and safety.

Why can't API keys use ENV variables or a secret management system where keys are not exposed in plain text?

Only account owners or administrators with Developer mode enabled can view tokens as needed for debugging purposes. API tokens have two classifications:

• integrator.io tokens: Allow  users to perform Create, Read, Update, or Delete (CRUD) operations support unless used for Integration Apps. integrator.io tokens are restricted restricted from creating or deleting Integration App data. Updates are also limited to specific fields that can only be configured from within the user interface.
• Integration App tile level tokens: Can't perform Create, Read, Update or Delete (CRUD) operations. They are only used to trigger exports and imports to view debug logs. 

Why does the API key require full access and not read only?

The main purpose of the tokens is to enable developers to debug or build features on integrator.io via the API (instead of through the user interface).

Why did we not get this alert in the test environment and only in the production environment?

An alert is always triggered if an API key is viewed in plain text. Contact Celigo support if you don't receive a notification.

Is the API key protected behind a secure login or are these workflows available widely? If it is protected behind a login who are the people with access to this?

Only users logged in as account owners or administrators can view API keys.

Do we have any audit mechanism to who is logging in to the accounts that have access to the key?

Tokens have audit info like any other integrator.io resource.