Set up API key access

When external applications access PPM, they can use API keys for authentication.

Overview

API key authentication provides a secure authentication mechanism for external applications accessing PPM's API.

The PPM administrator generates and manages the list of API keys for PPM.

  • Each API key includes a secret key for applications to use when authenticating. The secret key is like a user password and should be recorded securely.

  • Each API key is associated with a PPM user. Therefore, when an application uses an API key to access PPM, the application is limited by the associated user's permissions.

  • Only enabled API keys can be used to access PPM.

Back to top

Create API keys

This section describes how to create API keys.

Prerequisites:

  • You must have the Manage API Keys access grant.

  • Turn on the API Keys Authentication feature toggle.

To create a new API key:

  1. Click the Administration button in the masthead.

  2. From the Administration menu, select Integrations > Manage API Keys.

  3. Click Create.

  4. In the Add New API Key for User window, enter the following information:

    Field Description
    Name Provide a name for the API key.
    User Select the user to associated with the key.
    Description (Optional) Provide a description for the key.
    Expiration Date

    (Optional) Set an expiration date for the key.

    If no expiration date is set, API keys do not expire unless revoked.

  5. Click Create.

  6. In the API Key Created Successfully dialog box, click the Copy to Clipboard button to copy the secret key and send it to the user who needs to use this key for authentication. For details about how to authenticate using API keys, see API key authentication.

    PPM generates each secret key only once, and the secret key cannot be retrieved later. If the secret key is lost, create a new one.

  7. Click OK. The API key is enabled by default.

Back to top

Enable API keys as bearer tokens

API keys can be used as bearer tokens for REST API authentication. When enabled as bearer tokens, API keys can be included in the authorization header during REST API calls, granting access to the bearer. These keys should be included in the header for each API call, and the session closes once the call completes.

To enable an API key as a bearer token:

  1. Locate the target API key.
  2. Select the Bearer Token check box.

For details on how to use API key as bearer tokens, see Bearer authentication.

Back to top

Deactivate and reactivate API keys

You can deactivate an API key when you want to temporarily block the API key from accessing PPM.

To deactivate an API key:

  1. Open the Manage API Keys page. For details, see Create API keys.

  2. Select the API key you want to deactivate, and clear the Enabled check box.

    After you deactivate an API key, the user associated with the key is blocked from accessing PPM with the key.

To reactivate an API key:

Select the API key you want to reactivate, and select the Enabled check box.

Back to top

Revoke API keys

When you revoke an API key, the user associated with the key is permanently blocked from accessing PPM with the key.

To revoke an API key:

  1. Select the API key you want to revoke.

  2. Click the Revoke button .

  3. Click Yes. The API key is deleted from the grid.

    Note: If a user is deleted from PPM, all the user's API keys are revoked automatically.

Back to top

See also: