Share this page

# API access

You can enable API access for external tools that need to communicate with OpenText Software Delivery Management.

In this topic:

## Overview

For external tools to access OpenText Software Delivery Management, you must grant them registered access keys. The tools use the access keys for authentication when communicating as clients.

When you add API access, you can choose one of these key types:

- Credential. Uses a client ID and client secret.

- Token. Uses a single token value.

Tools that need authentication include:

- The Application Automation Tools and CI plugins. For details, see CI server integration.

- The interactive API client.

- Other 3rd-party tools and APIs that need to communicate through integration, such as those located behind a firewall.

- Auto actions within a release process. For details, see Auto actions.

You can generate either a local API access key or a federated client ID (OAuth 2.0 access token). For details on OAuth 2.0 authentication, see Authentication.

Note: For details on creating API access keys through the REST API, see API access keys (technical preview).

## Integration types

When providing API access to tools, integration types are automatically assigned to each tool. The default integration type is 3rd-party integration. Other integration types can be assigned, based on the roles you assign to the tool.

When viewing the list of external tools that have been granted API access in the grid, you can see each tool's integration type, but you cannot modify the type.

Note: Most roles can be customized. Roles and their permissions might be different for your organization.

Integration type | Description | Role
--- | --- | ---
CI/CD Integration | Enables integration with CI/CD servers such as Jenkins and TeamCity. This integration connects on the shared space level. It can access any workspace on which the CI/CD Integration role is assigned. | CI/CD Integration
3rd-party Integration | Enables 3rd-party tools to integrate freely. You can use this integration type as a default, and define roles, to get exactly the access the tool needs. This integration operates on any workspace or space. | Any role can be assigned

## Create an API access key

This section describes how to create an API access key.

If the new key is replacing a previous one, you should revoke the previous key. For details, see API key maintenance.

To create an API access key:

1. Open the global menu and select Administration > General Settings.
2. Select a shared space .

3. Select the API Access tab

4. Click the + API Access button.

5. Provide a name for the access key.

   Note: The name of the API access key can include only English characters.

6. In the Type field, select Credential or Token.

7. (Optional) Set an expiration date for the API key, and enter a description if needed. This can be useful if you want to provide a third-party with API access for a limited time.

8. To authenticate your API and other integrations using a federated identity (OAuth 2.0), select the Set a federated client ID checkbox, and enter the your organization's client ID.

   Note: This checkbox is only available if token exchange is activated in the sso.conf file. For details, see Configure OAuth 2.0 for API keys.

9. Assign to workspaces and roles:

   Field | Description
   --- | ---
   Role | Select the role that the tool uses to access OpenText Software Delivery Management. For a description of the predefined roles, see Predefined roles.
   In workspaces | Select the workspaces that the access key is assigned to: To assign to all workspaces, select [All workspaces]. The access key is assigned to all existing workspaces and to all future workspaces. The key is also assigned to deactivated workspaces when they are reactivated. To assign to selected workspaces, select workspaces in the list.

   To select more roles, click Add role to assign.

   Note:

   - For API access keys used for release process auto actions with authentication, you must assign the Release Manager role. For details, Auto actions.

   - For API access keys used for CI server integration, you must assign the CI/CD Integration role. These keys are used by the plugins that support CI integration, and when using the REST API to manage pipelines.

10. Click Add.

    A dialog box opens with the token or client ID/secret key. Copy the token or key to the clipboard. This is the only time that the newly-generated values will be visible. You must either use them immediately, or save them somewhere for later use.

11. Click OK. The access ID or OAuth 2.0 access token is added to the grid with an Active status.

## Cross-space API keys

If your organization manages multiple spaces, you can enable the use of the same API keys in all the spaces.

### Prerequisite

Set the following site parameters:

Parameter | Set to value
--- | ---
SUPPORT_API_ACCESS_CROSS_SPACES | true
RESTRICT_API_ACCESS_CROSS_SPACES_ASSIGNMENT Note: If the parameter is set to true, cross-space API keys can be shared across spaces that belong to the same API keys group. Set the Api keys group value for selected space in the Spaces grid in the Site settings. | false

For details, see Configuration parameters.

To create cross-space API keys:

1. Create an API key in one of the spaces. For details, see Create an API access key.

   Copy the Client ID. You will need to enter the same client ID in the other spaces.

2. Open another space. Click the arrow next to the API access button and select Cross-space API access. The Add cross-space API access dialog box opens.

3. In the Cross-space client ID field, enter the client ID from the first space.

4. Assign roles and workspaces for the API key in the current space.

   The new API key has the same client ID and secret as the original API key.

5. Repeat steps 2-4 in all the spaces in which you want to share the same API key.

Cross-space APIs are indicated in the Is cross-space field.

For cross-space API keys, Deactivate and Activate are space-level actions that affect only the current space. Revoke and Regenerate are global actions that apply to all linked spaces.

To deactivate or reactivate a cross-space API key in the current space:

1. Open the global menu and select Administration > General Settings.

2. Select a shared space .

3. Select the API Access tab.

4. Select the cross-space API key and choose Deactivate to block access in the current space, or choose Activate to restore access in the current space.

Note:

- If you revoke, regenerate or change the expiration date of a cross-space API key, all the linked API keys will be updated accordingly.

- Deleting a cross-space API key from one space will not affect the linked API keys in the other spaces.

- If you delete all the linked cross-space API keys, the remaining linked API key will be switched to a regular single-space key.

- Cross-space API keys remain active even after disabling the cross-space API key support. You need to also delete the keys themselves.

## API key maintenance

API access keys can be in one of these states: Active, Deactivated, or Revoked.

When you deactivate a key, the key remains defined but cannot access the selected scope until it is activated again.

When you activate a deactivated key, access is restored without generating a new secret.

Cross-space API keys: An API key can be deactivated and reactivated at a space level. The key's state in one space does not affect its state in the other spaces. Revoking an API key revokes it across all the spaces.

The actions available for each key depend on its current state:

Current state | Available actions
--- | ---
Active | Deactivate, Revoke, Regenerate, Delete
Deactivated | Activate, Revoke, Regenerate, Delete
Revoked | Regenerate, Delete

To maintain API keys:

1. Open the global menu and select Administration > General Settings.

2. Select a shared space .

3. Select the API Access tab.

4. Perform one of the following actions:

   Action | Description
   --- | ---
   Modify a key's properties | To modify a key: Click a key's ID. Edit the key's expiration date, roles, name, and description.
   Deactivate a key's access | Select one or more active keys in the grid and click the Deactivate button.
   Activate a key's access | Select one or more deactivated keys in the grid and click the Activate button.
   Revoke a key's access | Select one or more keys in the grid and click the Revoke access button .
   Regenerate a key's access | Select one or more keys in the grid and click the Regenerate access button . New client secrets or token values are issued for the regenerated keys, based on the selected key type.

## Set an email address for API access

If an integration using an API access key sends emails, you can define the email address that is used for this purpose. Enter the email address in the SMTP_NOTIFICATION_SENDER_EMAIL parameter. For details, see SMTP_NOTIFICATION_SENDER_EMAIL.

## Access key language

When you send an API request using a local API access key, the response is returned in the language that was set as the default UI language when the access key was created.

You can change the access key language using a PUT request.

For a list of the possible language values, see DEFAULT_LANGUAGE.

Note: Space admin permissions are required. For details, see Roles and permissions.

The following example updates the language to Spanish for all access keys in a shared space.

Copy code

    PUT …/api/shared_spaces/<shared_space_id>/users?fields=api_access,language&query="is_api_key EQ true"
    {
        "data": [
            {
                "language": "lang.esp"
            }
        ]
    }

To change the language of a specific API key, filter by name. The name is the Client ID in the API Access tab.

Copy code

    PUT …/api/shared_spaces/<shared_space_id>/users?fields=id,language&query="name EQ 'aaa_635ejde8dlem3iomn3pw9zd4g'"

## See also

- Roles and permissions

https://admhelp.microfocus.com Software Delivery Management 8942
Tips to improve your search results... OpenText™ Software Delivery Management Help Center OpenText™ Software Delivery Management Help 26.3 All View Local Help Center View Online Help Center Version: