API Credentials

Overview

You must use API credentials to call a Control Hub REST API. An API credential consists of a credential ID and an authentication token.

When you create an API credential, Control Hub generates and then displays the credential ID and authentication token values. You must copy and store the authentication token in a secure location. You cannot retrieve the token value from Control Hub at a later time.

If you lose the authentication token or if the token becomes compromised, you can regenerate the API credential.

The API credentials that you create are associated with your user account. When you use the credentials to call a Control Hub REST API, the credentials are authorized to complete the tasks allowed by the roles and permissions assigned to your user account or to the groups that your user account belongs to.

For example, when you use an API credential to call the Control Hub REST API that starts a job, you have the required roles and permissions to start the job.

A user with the Organization Administrator role can also administer API credentials created by all users in the organization.

Creating API Credentials

You create and manage the API credentials associated with your user account. Control Hub limits the number of API credentials to 10 per user.

To create an API credential, click Manage > API Credentials in the Navigation panel and then click the Add New API Credential icon: .

Then, complete the following steps in the API credential wizard:
  1. Define the API Credential
  2. View the API Credential

Define the API Credential

Define the API credential name. Control Hub automatically generates the credential ID and authentication token.

  1. Enter a name for the credential.

    For example, if creating the credential for use in Data Collector orchestration stages, you might enter the name SDCOrchestrationPipelines.

  2. Click one of the following buttons:
    • Cancel - Cancels creating the credential and exits the wizard.
    • Save & Generate - Saves the credential definition and generates the credential ID and authentication token.

View the API Credential

Copy the generated authentication token value and save it in a secure location.

  1. Click the Copy to Clipboard icon () next to the Token property.
  2. Save the authentication token value in a secure location.
    Important: You cannot retrieve the token value from Control Hub at a later time. If you lose the authentication token or if the token becomes compromised, you can regenerate the credential.
  3. Click Close.

    The new credential displays in the API Credentials view with the generated credential ID.

Using Credentials to Call APIs

Use the generated credential ID and authentication token to call Control Hub APIs.

To view the available Control Hub REST APIs, click the Help icon in the top right toolbar, and then click RESTful API.

For example, to call an API using the curl command line tool, first define CRED_ID and CRED_TOKEN environment variables to store the generated values, as follows:
export CRED_ID="93e5703f-747d-4798-b3ab-53b97768da48"
export CRED_TOKEN="eyJ0eXAiJKV1QLCJhbciOiJu25lIn0.eyJzIjoiN2RlNDhkWJkM2VkMY1YmE5MmE4ZjRhMGY5YTcwMGQ3MzMxM2UzYjNkYjE0MzRiOWE3ZTRlMzE0ZTcwZmNlNjFkNTE3NTRhMTZhOWQ2YjFmYWY3MjYyNjc4M2ViMWRkOTMyYMzZDFlMmJmYjU2YjYYTE1ODI2Y2Vlc3MiOiJkZXYiLCJqdGkiOiI5M2UNzAzZi03NDdkLTQOTgtYjNhYi01MI5Nzc2OGRhNDgiLCJvIjoiYTdmODJhNTctYjdlMy0xMWViLWI5M2MtY2RkMmVkMWYzNGMxIn0."

Then call the APIs using those environment variables.

For example, to get current user details from the API, use the following command:
curl -X GET https://na01.hub.streamsets.com/security/rest/v1/currentUser -H "Content-Type:application/json" -H "X-Requested-By:curl" -H "X-SS-REST-CALL:true" -H "X-SS-App-Component-Id: $CRED_ID" -H "X-SS-App-Auth-Token: $CRED_TOKEN" -i
Note: You also use API credentials to configure Data Collector orchestration stages that connect to Control Hub.

Regenerating API Credentials

If you lose the authentication token for a credential or if the token becomes compromised, you can regenerate the API credential. When you regenerate a credential, Control Hub retains the credential name and ID, but generates a new authentication token.

  1. In the Navigation panel, click Manage > API Credentials.
  2. Select the API credential, and then click the Regenerate icon: .
  3. Click OK to confirm.

    The Regenerate API Credential window displays the newly generated authentication token.

  4. Copy the generated authentication token value and save it in a secure location.
  5. Click Close.

Activating or Deactivating API Credentials

API credentials must be active to use the credentials to call a Control Hub REST API.

You can temporarily deactivate an API credential to disable using that credential to access Control Hub.

  1. In the Navigation panel, click Manage > API Credentials.
  2. Select one or more API credentials, and then click one of the following icons:
    • Activate icon () to activate the credential
    • Deactivate icon () to deactivate the credential

Renaming API Credentials

You can rename an API credential. Renaming a credential simply changes the display name of the credential in the API Credentials view.

Renaming a credential does not change the generated credential ID or authentication token.

  1. In the Navigation panel, click Manage > API Credentials.
  2. Hover over the credential that you want to rename, and then click the Rename icon: .
  3. Enter a new name, and then click Save.

Deleting API Credentials

When needed, you can delete API credentials. You can delete active or deactivated API credentials.

  1. In the Navigation panel, click Manage > API Credentials.
  2. Select one or more API credentials, and then click the Delete icon: .
  3. Click Delete to confirm the deletion, and then click Close.

Administering API Credentials

A user with the Organization Administrator role can administer API credentials created by all users in the organization.

As an organization administrator, you can activate, deactivate, or delete API credentials created by other users. You cannot create or regenerate API credentials for other users.

For example, as an administrator, you might need to deactivate another user's API credential to temporarily disable that user's access to the Control Hub API.

When you sign in as an organization administrator, the API Credentials view lists the credentials created by all users in the organization. The view lists only the credential name, ID, status, and the user that created the credential. The view does not display the authentication token value, which is accessible only at the time that the credential is created. You can filter the list by user.

Note: When a user is deleted, all API credentials created by that user are also deleted.