Documentation

Mistake on this page? Email us
Docs › Setting up your account › API keys

API keys

API keys allow applications (mobile, web and so on) to access the Device Management service APIs and SDKs for a specific team and its devices.

Once an API key exists, it does not authenticate against your user account again. If you give the key to anyone, the only way to stop them using it is deactivating or deleting the key.

Default access rights

An API key has the following defaults:

  • Its initial permissions are from the Developers user group.

    You can give the key greater access by associating it with the Administrator group, but only if you are an administrator, yourself.

    Tip: If you want developers to be able to use the APIs to create new API keys, you need to create an API key with administrator access permissions.

  • Its team and user association is to your team and user.

    "Your team" means the team you used to create the API key. That is the team you were logged in to Portal with, or the team of the administrator key you used to create the new key (with the APIs).

    You can change the user association (key owner) when editing a key, but you can never change a key's team association.

Using the APIs to create and manage API keys

You can create a new API key using an HTTP request to the Account Management API: Use the /v3/api-keys endpoint.

You can only perform this action if you authenticate it with an administrator's API key. In other words, you must already have at least one administrator key before you can use the APIs to create any other keys.

You can also use the Account Management API to manage existing keys. If you send the request with an administrator's API key, you can manage all API keys. If you send the request with a developer API key, you can only manage that key. In other words, a developer key can only manage itself.

Using API keys in Secure Device Access (SDA)

You can add keys to groups, limiting the keys' permissions according to the access policy that applies to that group. For more information, see the Secure Device Access chapter.

Creating a key

To create a new API key:

  1. In Access Management > API keys, click New API key.

    The Create API key pop-up opens.

  2. Give the API key an easily recognizable name.

  3. By default, an API key uses the Developer group's access permission. You can associate it with a different group either when creating it or later (see Managing existing API keys).

  4. Click Create API key.

  5. The API key is displayed as plain text, with a Copy to Clipboard button.

    You won't be able to see the API key again; please copy it to a safe location.

Managing an existing key

For an existing API key, you can:

  • View its details.
  • Rename the key.
  • Associate the key with a group.
  • Associate the key with a user (key owner).
  • Deactivate the key.
  • Delete the key.

Note: If you are a developer, you can only manage API keys you created. If you are an administrator, you can manage any API key your team has.

Viewing and editing a key

To view and edit key details:

  1. In Access Management > API keys, click the key name.

    You can only edit one key at a time.

  2. The API key pane opens.

  3. The pane has an Edit button that opens the Edit API key pop-up. The available actions are:

    • Rename.

    • Deactivate or reactivate. These actions are explained in the next section.

    • Change key owner (user):

      • You can select another user from the team. Do this if the current owner is no longer a member of the team, if you created all the keys but want to associate them with other members of your team or for other team management considerations.
      • If the key's owner is deleted, the key becomes inactive. You must set a new owner to activate the key.

    • Add and remove the key from groups. You can select the default Developers and Administrators groups, or groups your team has set up (usually for SDA).

      To add a group, select it from the list. To remove a listed group, click its name below the list.

The pane has two tabs that do not offer actions:

  • Summary: Basic key information, including the API host URL this API key can authenticate with, and the first eight characters of the public portion of the key.
  • Attributes: Full key information as returned by the API, including the public portion of the key.

Deactivating, reactivating and deleting a key

You can temporarily deactivate a key or permanently delete it:

  • Deactivating an API key is one of the options available when editing a key. Use this option if you are still not sure you want to delete the key and want to suspend its access while you investigate.

    You can reactivate the key if you are sure it’s safe.

    Note: Keys are automatically deactivated if their owner is deleted, and you must set a new owner before you can reactivate the key.

  • Deleting an API key is available in the API key pane for each key, or as a bulk action from the keys list. Deleting an API key can't be undone. If you're not sure you should delete it, consider temporarily deactivating it.

    Situations in which you may want to delete an API key:

    • Depending on your account type, you may have a limited number of API keys. If you've reached your limit, you must delete an existing key to create a new one.
    • If you think your API key was exposed to a third party or any other unauthorized persons.
    • For any other security consideration. For example, if you no longer use and maintain the application that relied on a specific key, it's good practice to remove the key in case the unmaintained application has a security vulnerability.

Using the keys

Previous