Set up API key access

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

API key authentication overview

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

  • Each API key includes a Client ID and an API Key for applications to use when authenticating.
  • Each API key is associated with an ALM user. Therefore, when an application uses an API key to access ALM, the application is limited by its user's permissions.
  • You can only use an active API key to access ALM.

  • If you deactivate or delete a user in ALM, the user's API keys are also deleted.

When writing ALM extensions or API scripts, obtain a Client ID and API Key from the administrator, and use them for authentication. For details on API key authentication when using REST and OTA, see the Developer Help.

Back to top

Work with API Keys

As an ALM site administrator, you can create, delete, revoke, and regenerate API keys. As a basic user, what you can do with your associated API keys depends on the setting of the APIKEY_SELF_SERVICE_LEVEL site parameter. For details about the parameter, see ALM Site Parameters.

SaaS: When managing API Keys, the options vary depending on the currently logged in customer administrator.

  1. (Optional) Define API key expiration time.

    By default, API keys do not expire unless being revoked. To set an expiration time, you can define the APIKEY_EXPIRE_DAYS site parameter. This parameter does not impact existing API keys.

    For details, see ALM Site Parameters.

  2. On the Application Lifecycle Management Options window, click the API Key link. In the API Keys Login window, enter your username and password.

  3. Manage API Keys.

    Create an API key

    To create an API key:

    1. Click API Access.

    2. In the API Key Name field, provide a name for the key.

    3. In the User field, select a user to associate with the key. The user permissions are granted to any application that accesses ALM using this API key.

      SaaS: The list of available users varies depending on the currently logged in customer administrator.

    4. Click Create.

      You receive a Client ID and API Key Secret, which you need to provide to the person who needs to use this key for authentication. Make a secure record of these, as the secret cannot be retrieved again. If it is lost, revoke the key and regenerate it to receive a new secret.

    The maximum number of API keys you can create for a user is restricted by the APIKEY_MAX_NUM_PER_USER site parameter. You cannot create or regenerate API keys for the user once the limit is reached. For details about the parameter, see ALM Site Parameters.
    Delete an API key

    To delete an API key, select the key from the list and click Delete Key.

    The API key owner will receive a notification email that the key is deleted. If you are a basic user with full control of your API keys, you will not receive notifications when you delete your own API keys.
    Revoke an API key

    Revoke an API key when you want to temporarily block the API key from accessing ALM.

    To revoke an API key, select the key from the list and click Revoke Key.

    The API key owner will receive a notification email that the key is revoked. If you are a basic user with full control of your API keys, you will not receive notifications when you revoke your own API keys.
    Regenerate an API key

    You can regenerate a revoked API key, which reactivates the key and provides a new API Key Secret to use with the original Client ID.

    To regenerate an API key, select the key from the list and click Regenerate Key.
    Refresh Click Refresh to refresh the list of API keys.
    Check Expiration Date

    The Expiration Date column displays when an API key expires.

    If an API key expires within 10 days, a warning appears next to the expiration date: Will expire in <N> days. The API key will expire at midnight (12:00 a.m.) on the expiration day.

Back to top