Add roles to your API key

Grant your API key permissions by adding one or many roles to it

In this topic, you’ll find the step-wise procedure to adding roles to your API keys. Through API key roles, you can determine what authorization your connected systems should have.


  • You know what API keys are
  • You are able to create API keys
  • You have identified your API key needs and have decided what permissions they need

Read more about:

Add a role when creating an API key

When creating an API key, you must choose an appropriate role. It could be a role you’ve created before but can also be one you create as you make the API key. When doing the latter, make sure your user has the roles.create permission.

If you proceed with your admin account, you will, by default, have all necessary permissions.

Continue by following these steps:

  1. In the API key creation form, use the roles & access field to assign a role
  2. (Optional): Create a new role
  3. Submit API key creation

You have now added a role to the API key while creating it.

Note: If you cannot create an API key, your user most likely does not have the service-accounts.create permission. Did your acting superior grant you the appropriate permissions?

Add a role by editing an API key

You can also add API key roles by modifying your API keys. To do so, you must have the service-accounts.update permission.

Proceed by doing the following:

  1. Navigate to the "Development" s tab in the web environment
  1. Find the API key you’d like to edit and press the ‘edit’ button
  1. Add the role you’d like to add
  2. Confirm your changes by pressing save

You have now edited your API key.

Note: You can create new roles when modifying API keys too.

Best practices: Determine your system permissions

When you add a role to an API key, it automatically inherits all permissions from that particular role. Thus, giving the system which utilizes the API key full autonomy to perform any behavior within that role’s permitted boundaries.
Consider creating various levels of authorization. You could do this by creating generic roles for each authorization level. Alternatively, you may wish to consider creating a unique role per system – ensuring security by operating on a case-by-case basis.