Service accounts - Temporal Cloud feature guide

Temporal Cloud provides Account Owner and Global Admin roles with the option to create machine identities named Service Accounts.

Service Accounts are a type of identity in Temporal Cloud. Temporal Cloud supports User identities as a representation of a human user who uses Temporal Cloud. Service Accounts afford Temporal Cloud Account Owner and Global Admin roles the ability to create an identity for machine authentication, an identity not associated with a human user.

With the addition of Service Accounts, Temporal Cloud now supports 2 identity types:

• Users (Tied to a human, identified by email address or id)
• Service Accounts (Not tied to a human, email address optional, identified by name or id)

Service Accounts use API Keys as the authentication mechanism to connect to Temporal Cloud. Use Service Accounts to represent a non-human identity when authenticating to Temporal Cloud for operations automation or the Temporal SDKs and the Temporal CLI for Workflow Execution and management.

Get started

To get started with Service Accounts, ensure youʼre a Temporal Cloud user.

Prerequisites:

• A Cloud user account with Account Owner or Global Admin role permissions
• Access to the Temporal Cloud UI or Temporal Cloud CLI (tcld)
• Enable access to API Keys for your Account
• To manage Service Accounts using the Temporal Cloud CLI (tcld), upgrade to the latest version of tcld (0.18.0 or higher) using brew upgrade tcld, and enable the Service Account commands with tcld feature toggle-service-account.

Managing Service Accounts

Account Owner and Global Admin roles can manage Service Accounts by creating, viewing, updating, deleting Service Accounts using the following tools:

• Temporal Cloud UI
• Temporal Cloud CLI (tcld)
  • Use tcld service-account --help for a list of all service-account commands

Account Owner and Global Admin roles also have the ability to manage API Keys for Service Accounts.

Create a Service Account

Create a Service Account using the Temporal Cloud UI or tcld. While User identities are invited to Temporal Cloud, Service Accounts are created in Temporal Cloud.

Using the Cloud UI

1. Navigate to https://cloud.temporal.io/settings/identities
2. Click the Create Service Account button located near the top right of the Identities & API Keys page
3. Provide the following information:

• Name (required)
• Description (optional)
• Account Level Role (required)
• Namespace Permissions (optional)
  • Use this section of the Create Service Account page to grant the Service Account access to individual Namespaces

4. Click Create Service Account at the bottom of the page

• A status message is displayed at the bottom right corner of the screen and on the next screen
• You will be prompted to create an API Key for the Service Account (optional)

5. (Optional) Create API Key

• It is recommended to create an API Key for the Service Account right after you create the Service Account, though you can create/manage API Keys for Service Accounts at any time.
• See the API Key documentation for more information on creating and managing API Keys.

Using tcld

To create a Service Account using tcld, use the tcld service-account create command:

tcld service-account create -d "this is a test SA" -n "sa_test"

This example creates a Service Account with a name (-n) of "sa_test", a description (-d) "this is a test SA" and an Account Role of Read.

Creating a Service Account requires the following attributes: name and account-role. You can also provide Account Roles and Namespace Permissions for the Service Account using the —-ar and —-np command flags. Creating a Service Account returns the ServiceAccountId which is used to update or delete a Service Account.

View Service Accounts

View a single or all Service Account(s) using the Temporal Cloud UI or tcld.

Using the Cloud UI

Service Accounts are listed in line with User Identities. To locate a Service Account, look for identities that include the Service Account icon.

1. Navigate to https://cloud.temporal.io/settings/identities
2. Look for the Service Account icon next to an identity

Using tcld

To view all Service Accounts in your account using tcld, use the tcld service-account list command:

tcld service-account list

Delete a Service Account

Delete a Service Account using the Temporal Cloud UI or tcld.

Using the Cloud UI

1. Navigate to https://cloud.temporal.io/settings/identities
2. Find the Service Account you would like to delete
3. Click the three vertical dots in the Service Account row
4. Select Delete from the menu displayed
5. Confirm the Delete action when prompted

Using tcld

To delete a Service Account using tcld, use the tcld service-account delete command:

tcld service-account delete --service-account-id "e9d87418221548"

Use the tcld Service Account list command to validate the Service Account has been removed from the account. The Service Account is deleted when it is no longer visible in the output of .

Update a Service Account

Update a Service Accountʼs description using the Temporal Cloud UI or tcld.

Using the Cloud UI

1. Navigate to https://cloud.temporal.io/settings/identities
2. Find the Service Account you would like to update
3. Click the three vertical dots in the Service Account row
4. Select Edit from the menu displayed
5. Make changes to the Service Account. You can change the Service Account's name, description, Account Level Role, and Namespace Permissions.
6. Click the Save button located in the bottom left of the screen. A status message is displayed at the bottom right corner of the screen.

Using tcld

Three different commands exist to help users update a Service Account using tcld:

• tcld service-account update: To update a Service Account's name or description field
• tcld service-account set-account-role: To update a Service Account's Account Role
• tcld service-account set-namespace-permissions: To update a Service Account's Namespace Permissions

Example:

tcld update --id "2f68507677904e09b9bcdbf93380bb95" -d "new description"