Skip to main content

Manage Service Accounts

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. You should 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.

tip

Namespace Admins can now manage and create Namespace-scoped Service Accounts, regardless of their Account Role.

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

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 (v0.18.0 or higher) using brew upgrade tcld.
    • If using a version of tcld less than v0.31.0, enable Service Account commands with tcld feature toggle-service-account.

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.

  1. Go to Settings → Identities
  2. Click the Create Service Account button located near the top of the Identities 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

View Service Accounts​

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

Service Accounts are listed on the Identities section of the Settings page, along with Users. To locate a Service Account:

  1. Go to Settings → Identities
  2. Select the Service Accounts filter

Delete a Service Account​

Delete a Service Account using the Temporal Cloud UI or tcld. When you delete a Service Account, all associated API keys are automatically deleted as well. Therefore, you don't need to manually remove API keys after deleting a Service Account.

  1. Go to Settings → Identities
  2. Find the relevant Service Account
  3. Select the vertical ellipsis menu in the Service Account row
  4. Select Delete
  5. Confirm the delete action when prompted

Update a Service Account​

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

  1. Go to Settings → Identities
  2. Find the relevant Service Account
  3. Select the vertical ellipsis menu in the Service Account row
  4. Select Edit
  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

Namespace-scoped Service Accounts​

There is a special type of Service Account, called a Namespace-scoped Service Account, which shares the same functionality as the Service Accounts above, but is limited (or scoped) to a single namespace.

In particular, a Namespace-scoped Service Account must always have:

  • A Read Account Role
  • A single Namespace Permission

Note that a Namespace-scoped Service Account cannot be reassigned to a different Namespace after creation, but its Namespace permission can be modified (e.g. from Read to Write).

Namespace-scoped Service Accounts are useful in situations when you need to restrict a client's access to a single Namespace.

You can retrieve, update, and delete a Namespace-scoped Service Account using the same process and commands as above, but creation is slightly different.

Permissions​

Unlike regular Service Accounts, which require a Global Admin or Account Owner role, Namespace-scoped Service Accounts can be created and managed by Namespace Admins. For example, an Account Developer with Namespace Admin for test_ns can create a Service Account scoped to test_ns.

Global Admins and Account Owners can also create Namespace-scoped Service Accounts, as they implicitly have Namespace Admin rights for all Namespaces.

Create a Namespace-scoped Service Account​

As with regular Service Accounts, Namespace-scoped Service Accounts can be created using Temporal Cloud UI or tcld.

Using the Cloud UI​

Currently, creating a Namespace-scoped Service Account from the Temporal Cloud UI happens on an individual Namespace page. If the current Namespace has API key authentication enabled, then there will be a Generate API Key button as a banner on the top of the Namespace page or in the Authentication section.

By clicking on the Generate API Key button, a Namespace-scoped Service Account will be automatically created for the given Namespace (if one does not already exist) and an associated API key will be displayed. This key will have the maximum expiration time, which is 2 years.

The resulting Namespace-scoped Service Account will be named <namespace>-service-account and will have an Admin Namespace permission by default.

Using tcld​

To create a Namespace-scoped Service Account with tcld, use the tcld service-accounted create-scoped command:

tcld service-account created-scoped -n "test-scoped-sa" --np "test-ns=Admin"

This example creates a Namespace-scoped Service Account for the Namespace test-ns, named test-scoped-sa, with Admin Namespace Permission. Note that the Account Role is omitted, since Namespace-scoped Service Accounts always have a Read Account Role.

Lifecycle​

When a Namespace is deleted, all associated Namespace-scoped Service Accounts and their associated API keys are automatically deleted as well. Therefore, you do not need to manually remove Namespace-scoped Service Accounts and their API keys after deleting a Namespace.