Creating a service account with account/service-accounts - Cloud

Talend Cloud APIs User Guide

Version
Cloud
Language
English (United States)
Product
Talend Cloud
Module
Talend API Designer
Talend API Tester
Talend Data Preparation
Talend Data Stewardship
Talend Management Console
Content
Design and Development > Designing APIs
Design and Development > Testing APIs

Call the account/service-accounts endpoint to create a service account and then generate a token for this account.

  • A service account always needs a token to access Talend Cloud. In addition, this account also needs appropriate permissions to call the Talend service to be used.
  • This token used by service accounts is not a personal access token. It needs to be generated as explained in the following procedure.

Before you begin

  • Ensure that the user that issues API calls has the Service Account - Manage permission. The ID of this permission is TMC_SERVICE_ACCOUNT_MANAGEMENT.
  • Ensure that the service account feature is available to your account.

About this task

In this section, the following API call is issued:
method: POST
endpoint: https://api.<env>.cloud.talend.com/account/service-accounts
headers: {
 "Content-Type": "application/json",
 "Authorization": "Bearer <your_personal_access_token>"
}
payload: {
  "name": "myServiceAccount",
  "permissions": [
     "TMC_USER_MANAGEMENT",
     "TMC_ROLE_MANAGEMENT",
     "AUDIT_LOGS_VIEW",
     "TMC_ENGINE_USE"
  ]
}
It is implemented in Talend API Tester for demonstration purposes.

Procedure

  1. If you do not have a personal access token yet, on the Profile preferences page, generate a personal access token for your account.
    For further information, see Generating a Personal Access Token.
  2. Select POST from the Method list and in the field aside, enter the service account management endpoint to be used: https://api.<env>.cloud.talend.com/account/service-accounts

    Example

  3. Click Add header twice to add tow rows and enter the following key:value pairs.
    • Content-Type : application/json.
    • Authorization : Bearer <your_personal_access_token>
  4. In the BODY area, enter the profile of the service account to be created.

    Example

     {
      "name": "myServiceAccount",
      "permissions": [
         "TMC_USER_MANAGEMENT",
         "TMC_ROLE_MANAGEMENT",
         "AUDIT_LOGS_VIEW",
         "TMC_ENGINE_USE"
      ]
    }

    In this example, the four permissions, TMC_USER_MANAGEMENT, TMC_ROLE_MANAGEMENT, AUDIT_LOGS_VIEW and TMC_ENGINE_USE are assigned to this service account. With these permissions, this service account can manage user accounts, access audit logs and run tasks.

    The following permissions are typically useful for your service accounts:
    Permission names Permission IDs
    Users - Manage TMC_USER_MANAGEMENT
    Roles - Manage TMC_ROLE_MANAGEMENT
    Groups - Manage TMC_GROUP_MANAGEMENT
    Service Account - Manage TMC_SERVICE_ACCOUNT_MANAGEMENT
    Audit logs - View AUDIT_LOGS_VIEW
    Engines - Use TMC_ENGINE_USE

    For more permissions available for granting to service accounts, use GET at the account/service-accounts/permissions endpoint to get the list.

  5. Click Send to issue your call.

    The service account is created and the status code 201 is returned. In the BODY field of the response, the details of this created service account are displayed.

    • Note down the ID value and the secret in this response, as you need them to generate a token for this new service account.
      • This is the only time you can see the secret.

      • The secret must be safely stored, or even encrypted, so as to be protected against inappropriate use.
    • This ID and this secret cannot be changed and will not expire. If you need to change them, you have to remove this service account and create a new one.
  6. Click Save as to save this API call on Talend API Tester so that you can directly use it when needs be.
  7. Combine the ID and the secret of the service account in the following format: ID:secret and paste this combination to a Base64 encode application of your choice to encode this pair.
    • You need to use the encoded value of this ID:secret pair to generate a service account token in a secured manner.

What to do next

Generate a service account token to make this service account usable.