API Credentials

The StreamSets Platform SDK for Python uses API Credentials for authentication.

The Platform SDK also supports management of API credentials for Control Hub, including creation of credentials for themselves or, for other users, deletion of credentials, activating or deactivating existing credentials and, renaming credentials.

For more details, refer to the StreamSets Platform Documentation.

Note

Currently, you need to create a set of API credentials via the Platform UI before being able to use the Platform SDK. The actions below are possible only after having at least 1 set of API credentials.

Creating API Credentials

To create API credentials in the Platform UI, you go to Manage > API Credentials and click on the + icon.

To accomplish the same task using the Platform SDK, you need to instantiate a streamsets.sdk.sch_models.ApiCredentialBuilder instance and, create a new streamsets.sdk.sch_models.ApiCredential object.

To instantiate the builder instance use streamsets.sdk.ControlHub.get_api_credential_builder() method. You can then call the streamsets.sdk.sch_models.ApiCredentialBuilder.build() method to create the new API credentials and give them a name by supplying a value for the name parameter.

After creating the new API credentials, pass the resulting streamsets.sdk.sch_models.ApiCredential to the streamsets.sdk.ControlHub.add_api_credential() method to register the credentials in Platform.

# Instantiate the ApiCredentialBuilder
credential_builder = sch.get_api_credential_builder()

# Give a name to the credentials
new_credentials = credential_builder.build(name='name for new credentials')

# Add them to Platform
sch.add_api_credentials(new_credentials)

Note

The attributes credential_id and auth_token are only populated once the credentials are registered on Platform.

Warning

The credential_id and auth_token values for a set of API credentials are private key values and should be safeguarded as sensitive passwords. These values are not retrievable after the API credentials have been created. If the resulting API credentials are deleted from local memory and the values are not stored, they will be lost.

Creating API Credentials For Other Users

You can also create API credentials on behalf of other users in your organization using the Platform SDK.

The steps to create credentials on behalf of other users are almost identical to the steps in the above section with one additional requirement: you must pass the ID of the user you wish to create credentials for to the streamsets.sdk.sch_models.ApiCredentialBuilder.build() method via the user_id parameter.

Note

This can only be done by users with Organization Administrator privileges.

user = sch.users.get(id='<existing user id>')
credential_builder = sch.get_api_credential_builder()

# pass the user id here
new_credentials = credential_builder.build(name='Credentials for Costanza', user_id=user.id)

# add it to Control Hub
sch.add_api_credentials(new_credentials)

Note

This method can be used for creating API credentials for Service Accounts. You must have Service Accounts enabled for your organization.

Regenerating Auth Token

It’s possible to regenerate the auth token value for an API credential while also keeping the same credential ID.

To do so in the Platform UI, you can click on the additional options menu next to the API Credentials and click on “Regenerate”.

To regenerate an auth token using the Platform SDK, you can use the streamsets.sdk.ControlHub.regenerate_api_credential_auth_token() and pass it the appropriate streamsets.sdk.sch_models.ApiCredential object.

lost_credentials = sch.api_credentials.get(name='regenerate every 2 weeks')

# regenerate them
sch.regenerate_api_credential_auth_token(lost_credentials)

# you can view the new auth token
lost_credentials.auth_token

Renaming API Credentials

You can change the name of your API credentials at any point.

To do so in the Platform UI, click on the additional options menu next to the API credentials and click on “Rename”.

To change the name of API credentials using the Platform SDK, you can directly set the name attribute of the appropriate streamsets.sdk.sch_models.ApiCredential object and then pass it to the streamsets.sdk.ControlHub.rename_api_credential() method.

name_change_credentials = sch.api_credentials.get(name='Stefani Joanne Angelina Germanotta')
name_change_credentials.name = 'Lady Gaga'
sch.rename_api_credential(name_change_credentials)

Note

It is possible to have multiple API credentials with the same name; they are differentiated based on their Credential ID.

Activating or Deactivating API Credentials

You can activate or deactivate a particular API credential at any point. This can be particularly useful as a security feature to limit others making changes while not deleting them completely.

To do so in the Platform UI, click on the additional options menu next to the API credentials and click on “Activate” or “Deactivate” based on your use case.

To activate or deactivate an API credential using the Platform SDK, you pass the appropriate streamsets.sdk.sch_models.ApiCredential object to the streamsets.sdk.ControlHub.activate_api_credential() or streamsets.sdk.ControlHub.deactivate_api_credential() methods, respectively.

You can also check if a credential is active via the streamsets.sdk.sch_models.ApiCredential.active attribute.

credentials = sch.api_credentials.get(credential_id='<some_id>')

# check if credentials are active
credentials.active  # True or False

# deactivate credentials
sch.deactivate_api_credentials(credentials)

# active credentials
sch.activate_api_credentials(credentials)

Note

Credentials are active when they are created.

Deleting API Credentials

You can also delete API credentials from your Platform organization at any time.

To do so in the Platform UI, click on the additional options menu next to the API credentials and click on “Delete API Credential”.

To delete API credentials using the Platform SDK, use the streamsets.sdk.ControlHub.delete_api_credentials() method and pass in one or more streamsets.sdk.sch_models.ApiCredential objects to be deleted.

credential_to_be_deleted = sch.api_credentials.get(name='old credential')

# delete a single credential
sch.delete_api_credentials(credential_to_be_deleted)

first_credential_to_be_deleted = sch.api_credentials.get(name='First')
second_credential_to_be_deleted = sch.api_credentials.get(name='Second')

# delete multiple credentials
sch.delete_api_credentials(first_credential_to_be_deleted, second_credential_to_be_deleted)

Bringing It All Together

The complete scripts from this section can be found below. Commands that only served to verify some output from the example have been removed.

# Get an API credential builder
credential_builder = sch.get_api_credential_builder()

# Create a credential with the builder for yourself
credential = credential_builder.build(name='Some Credential Name')

# Or build it for someone else
user = sch.users.get(name='Elaine Benes')
credential = credential_builder.build(name="Credentials for Elaine", user_id=user.id)

# Add it to Control Hub
sch.add_api_credential(credential)

# View the credentials that are just created
credential.credential_id

# Remembering, that auth token is only visible at time of creation
credential.auth_token

# You can always regenerate the tokens
sch.regenerate_api_credential_auth_token(credential)

# Deactivate them
sch.deactivate_api_credentials(credential)

# Or, activate them
sch.activate_api_credentials(credential)

# Rename them
credential.name = "Elaine Benes"
sch.rename_api_credential(credential)

# Or delete them
sch.delete_api_credentials(credential)