API key management

Site Administration enables you to create and manage API keys for external applications accessing ALM's API.

API key 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 Secret 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 associated 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

Permissions

By default, only site admins (for on-premises) and customer admins (for SaaS) can create and manage API keys for ALM users, using the Site Administration > Users > API Key Management tab. For details, see Create and manage API keys for any user.

If you are not a site or customer admin, you can create and manage your own API keys from Site Administration > My Settings > My API Key, depending on the setting of the APIKEY_SELF_SERVICE_LEVEL parameter. For details, see Create and manage your own API keys.

Back to top

Create and manage API keys for any user

As a site or custom admin, you can create, delete, revoke, and regenerate API keys for any active ALM user.

To create an API key:

  1. Open Site Administration > Users > API Key Management.

  2. Click Add API Key, and provide the following information:

    Field Description
    API Key Name Provide a name for the key.
    Owner

    Select a user to associate with the key. The user's 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 admin.
    Expiration Time

    Specify when the API key expires.

    The expiration time you set for this API:

    • Overrides the expiration time set globally by the APIKEY_EXPIRE_DAYS site parameter. For details, see ALM Site Parameters.

    • Should be no later than the value of the APIKEY_EXPIRE_DAYS site parameter.
    Scope

    Enable or disable OData for the API key.

    If you want to connect to ALM data from OData using API key authentication, enable OData for the API key. For details, see OData support for extended reporting.

  3. Click Create and note down the generated Client ID and API Key Secret.

    Make a secure record of the generated Client ID and API Key Secret and provide them to the associated user. Once generated, the client ID and API key secret cannot be retrieved again. If they are lost, revoke the key and regenerate it.

Note: 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.

To delete an API key:

Select the key from the list and click Delete Key.

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

To revoke an API key

Revoke an API key if you want to temporarily block the API key owner from using the API key to access ALM.

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

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

To regenerate a revoked 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. Click the copy button to note down the new API key secret.

Back to top

Create and manage your own API keys

If permitted, you can view, create, or edit your own API keys without admin permissions.

Prerequisite:

Whether you, as a basic user, can create and manage your own API keys depends on the setting of the APIKEY_SELF_SERVICE_LEVEL parameter. For details, see APIKEY_SELF_SERVICE_LEVEL.

To create and manage your own API keys:

  1. From the top right corner of Site Administration, click the log-in user icon > My Settings.

  2. Click the My API Key tab.

  3. View your API key details or create an API key for your account. See Create and manage API keys for any user.

Back to top

Filter API keys

You can filter API keys by user attributes such as API key name, status, and owner.

To filter API keys:

  1. Open the Site Administration > Users > API Key Management tab.

  2. Click Filter.

  3. Specify the following attributes by which API keys are filtered, and click Filter.

    • API Key Name. Shows API keys whose name is as specified.

    • Client ID. Shows the API key whose client ID is as specified.

    • Status. Shows API keys of a specific status: active, inactive, or revoked.

    • Owner. Shows API keys whose owner is as specified.

    • Created By. Shows API keys that are created by the user you specified.

    • Expiration Date. Shows API keys that expire by the specified date.

    • Never Expire. Shows API keys that never expire.

Back to top

API key site parameters

The following table lists the site parameters related to API keys. As a site admin, you can use them to control API key behaviors at site level.

Parameter Description
OTA_ACCESS_APIKEY_ONLY

This parameter is used to control whether 3rd-party applications can use username and password to get authenticated using the OTA API.

RESTAPI_ACCESS_APIKEY_ONLY This parameter is used to control whether applications can get authenticated using username and password using the REST API.
RESTAPI_WHITELIST_APIKEY This parameter is used to specify the client types of 3rd-party tools or applications that can log in with username and password using the REST API.
RESTAPI_DEFAULTLIST_APIKEY This parameter is used to specify the client types of internal tools that can log in with username and password using the REST API.
APIKEY_MAX_NUM_PER_USER This parameter defines the maximum number of active API keys each user is allowed to create. The default value is 10.
APIKEY_EXPIRE_DAYS

This parameter is used to specify the number of days after which all API keys expire globally.

The default value is -1, which means API keys never expire. If an API key has its expiration time specified separately, this parameter is overridden for the API key. For details, see Expiration Time.
APIKEY_SELF_SERVICE_LEVEL

This parameter is used to control what all ALM users can do with their API keys in the Site Administration > My Settings > My API Key page.

  • admin_only. You cannot create or manage your API keys. Only a site admin or customer admin can handle API keys for you from Site Administration > Users > API Key Management.

  • user_read_only. You cannot create or edit your API keys but can view your API keys details.

  • user_full_control. You have full control of your API keys, including creating, viewing , revoking, deleting, and regenerating your API keys.

For details, see ALM Site Parameters.

Back to top

API key troubleshooting

The following table lists the issues you may encounter when using API keys.

Issue Solution
Unable to connect to an external application using an existing API key after the upgrade Contact your site admin to make sure the confidential data passphrase and communication security passphrase are the same as the passphrases used for the previous version. Different passphrases between versions make the secrets of all existing API keys invalid.

Back to top