Skip to main content
How to create an Elements API Token

Elements API; Stories; Requirements; API Token; Integration; Developers

Ksawery Lisinski avatar
Written by Ksawery Lisinski
Updated over a week ago

What can the API be used for?

The Elements API is available to interact with Elements stories (requirements coming soon!), allowing you to create, read, update and delete your work items programmatically. Combined with an Elements Webhook, this infrastructure can help you integrate Elements work items with other external ticketing systems such as Salesforce, Azure DevOps, Service Now - any other system with an API available.

We recommend using a 3rd party integrations tool to assist you with building an integration.

To read our developer documentation go to developer.elements.cloud where you will find all our developer-friendly resources to help you get started with the Elements API.

Prerequisites:

  • Enterprise Space with the API capability activated

  • Space Admin permissions or API Token Manager permissions in the Space

Video overview

You can watch a video overview of creating an API token in Elements here.

How to give users API Token Manager permissions

This is done in Space Management by Space Admins. To allocate a user this permission, navigate to their account in the Users tab in Space Management.

From here, check the "API Token Manager" checkbox to allocate this permission.

Note that for security reasons, if you remove this permission from a user, all tokens generated by them will be automatically revoked. The same will occur for tokens generated by users removed from a space or deleted from Elements altogether.

You can also allocate this permission when inviting a new user to your space.

Generating a token

To generate a new API token for your Space navigate to the "Developer" tab in Space management. From here, open the "API Tokens" tab and select the blue "Create API Token" in the top right corner of the screen.

This will open a window where you can input a name, description, and select the token scopes you want. We recommend creating multiple tokens with limited scopes for security reasons.

Once you've pressed "Create" you will see the following screen with your API Token. This will only be shown to you once. Copy the token ID to your clipboard for use.

Once you close this window you will see your new token in the token list with associated information such as the date you created it and the last time it was triggered. You can edit the name and description at any time, but you cannot edit the scope.

Revoking a token

In cases where you no longer use a token, or need to change the scope of a token, you will need to revoke it.

You can revoke a single token by clicking "Revoke" in the right panel of the selected token, or alternatively you can revoke all the tokens in the space by clicking "Revoke all tokens" in the top right corner.

Note that if you are not a Space admin you will only see the tokens in that space that you have generated. Space Admins are able to see all tokens in the space by all users, and to revoke them all too.

Revoking a token is an irreversible action. You can easily create a new token if this was a mistake but must ensure you then update any system or integration settings where the token is used, as your old token will no longer be valid.

Permission considerations:

Permission restrictions on actions

The level of permissions you have in a space will have an affect on the use of API Tokens in Elements. For example, you will be able to create a token with a story create and edit scope, but if you do not have permissions to do this action in the space then you will be unable to do this via the API.

In short, you must ensure you are permitted to do the same actions in the space that you give to the token, as the API actions will be done via your user account in that space.

Visibility of tokens in your space

With either Space Admin or Token Manager permissions you will be able to generate a token in that Space. However, note that only Space Admins can view all the tokens that have been generated in a particular space and will be able to revoke all tokens by all users.

Additional information and resources

There is a limit of 10 tokens per user, and 50 tokens per space overall. You will see a message if you have gone over this limit. In this case we recommend revoking any tokens that you no longer use.

If you would like to discuss increasing this limit please contact us at success@elements.cloud.

Did this answer your question?