API access

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

In this topic:

Overview

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

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.

To view the list of API keys:

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

2. Select a shared space .

3. Select the API Access tab.

Back to top

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.

Back to top

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. (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.

7. Assign to workspaces and roles: 

   Field	Description
   Role	Select the role that the tool uses to access OpenText Core Software Delivery Platform. 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.

8. Click Add.

   A dialog box opens with a Client ID and a Client secret. Click Copy to save the keys to the clipboard. This is the only time that the newly-generated key will be visible. You must either use it immediately, or save it somewhere for later use.

9. Click OK. The access ID is added to the grid with an Active status.

Back to top

API key maintenance

You can modify, revoke, and regenerate API keys.

To maintain API keys:

1. Open the Settings menu , click Spaces, and select a space.

2. Select the API Access tab.

3. 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.
   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 are issued for the regenerated keys.

Back to top

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.

Back to top

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.

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

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.

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

See also:

• Roles and permissions