API access

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

Overview

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

Applications that need authentication include:

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

  • The interactive API client.

  • Other 3rd-party applications 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).

Back to top

Integration types

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

When viewing the list of applications that have been granted API access in the grid, you can see each application's integration type, but you cannot modify the type. You can access the grid here: Settings > Spaces > API Access.

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

Integration type Description Role
CI/CD Integration

This 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

This enables 3rd-party applications to integrate freely. You can use this integration type as a default, and define roles, to get exactly the access the application needs.

This integration operates on any workspace or space.

Any role can be assigned

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

To create an API access key:

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

  2. In the API Access tab, click the API Access button .

  3. Provide a name for the access key.

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

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

  5. 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 Set up SSO authentication.

  6. Select the roles for the applications to use when accessing OpenText Software Delivery Management. For a description of the predefined roles, see Predefined roles.

    For each role, select all of the relevant workspaces. If additional relevant workspaces are created later, you will need to manually assign them.

    You can select more than one role by clicking 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.

  7. Click Add.

    Local API key: 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.

  8. Click OK. The access ID or OAuth 2.0 access token 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:

    1. Click a key's ID.

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

See also: