Service accounts CLI

You can create service accounts and their tokens using the Jenkins CLI. The CLI provides commands to create, delete, and list service accounts and tokens, as well as manage group memberships.

OpenID Connect (OIDC) configurations cannot be managed using the CLI. To configure OIDC authentication for a service account, refer to:

Access CLI documentation

For complete documentation of CLI commands and their arguments, refer to the following:

Select in the upper-right corner of the operations center or controller dashboard to navigate to the Manage Jenkins page.
Select Jenkins CLI.
Download the Jenkins CLI JAR file and refer to the documentation on the Jenkins CLI page for usage instructions.

For more information about the Jenkins CLI, refer to Jenkins CLI tool.

Available CLI commands

The following CLI commands are available for managing service accounts:

list-service-accounts
create-service-account
delete-service-account
list-service-account-tokens
create-service-account-token
delete-service-account-token

All service account commands require a CONTAINER argument that specifies the scope: root for root scope, or a folder path such as my-team/dev for item scope.

When you create a token, it prints a randomly generated ID (in UUID format) as well as the token secret. The ID may be used to delete the token later. The secret must be copied at creation time; it cannot be retrieved later.

You can also manage service account group memberships using the group-membership CLI command. When adding or removing members, you must prefix the service account name with serviceAccount: to disambiguate it from users or groups with the same name.

The group-membership command operates on each member type independently (users, groups, and service accounts). When you specify service account members, it affects only the service account memberships in the group, leaving existing users and groups unchanged.

Examples

The following examples demonstrate common service account workflows using the CLI.

Replace my-operations-center.com/cjoc/ with the URL of your operations center or controller.
These examples use operations center URLs for simplicity, but in practice, most automation (such as triggering builds) should be performed on controllers where jobs run.
Replace username:apiToken with your credentials (either your username and API token, or a service account name and token with appropriate permissions).

Create and use a service account

This example creates a service account in a folder, creates a token, verifies authentication, adds it to a group, and then uses it to trigger a build.

Create a service account named bot in the my-team/dev folder:

java -jar jenkins-cli.jar -auth username:apiToken -s https://my-operations-center.com/cjoc/ create-service-account my-team/dev bot▼

Create a token for the service account with a description For CLI access:

java -jar jenkins-cli.jar -auth username:apiToken -s https://my-operations-center.com/cjoc/ create-service-account-token my-team/dev bot --description 'For CLI access'▼

If successful, the command outputs a randomly generated ID and token secret:

12345678-90ab-cdef-1234-567890abcdef cloudbees_ci_sa_abc123def456789012345678901234ef▼

Copy the token secret; it cannot be retrieved later. The ID can be used to delete the token.

Verify the service account token is working using the who-am-i CLI command:
```
java -jar jenkins-cli.jar -auth my-team/dev/bot:cloudbees_ci_sa_abc123def456789012345678901234ef -s https://my-operations-center.com/cjoc/ who-am-i▼
```
This displays the service account name and the cloudbees-ci-service-account authority, confirming it is a service account, rather than a human user.
Add the service account to the build-managers Role-Based Access Control (RBAC) group in the my-team/dev folder, prefixing the service account name with serviceAccount: to disambiguate it from users or groups with the same name:
```
java -jar jenkins-cli.jar -auth username:apiToken -s https://my-operations-center.com/cjoc/ group-membership my-team/dev build-managers serviceAccount:my-team/dev/bot▼
```

Use the service account to trigger a build of my-job in the my-team/dev folder:

java -jar jenkins-cli.jar -auth my-team/dev/bot:cloudbees_ci_sa_abc123def456789012345678901234ef -s https://my-operations-center.com/cjoc/ build my-team/dev/my-job▼