Service account API endpoints

You can create service accounts and their tokens using the REST API. The API provides endpoints to create, delete, and list service accounts and tokens, and to manage group memberships.

Access API documentation

For interactive REST API documentation:

Navigate to any relevant page in the operations center or controller UI (such as the Service Accounts page).
Select REST API at the bottom of the page.

The API documentation page provides both read-only JSON API endpoints and write operations for creating and deleting service accounts. You can also access the API documentation directly using the URL patterns in the table below.

Access API documentation using URL patterns

The following table summarizes the REST API documentation URL patterns for service accounts and groups.

Replace my-operations-center.com/cjoc/ with the URL of your operations center or controller.
When exploring the REST API in a web browser, add &depth=2 to include full information including tokens. In scripts, always use the tree parameter to select only the desired fields.

Table 1. REST API documentation URL patterns
Description	REST API documentation URL pattern
List service accounts and manage service account operations	Root scope: `https://my-operations-center.com/cjoc/serviceAccounts/api/`
List service accounts and manage service account operations	Item scope: `https://my-operations-center.com/cjoc/job/my-team/job/dev/serviceAccounts/api/`
View a specific service account and manage authentication methods	Root scope: `https://my-operations-center.com/cjoc/serviceAccounts/my-sa/api/`
	Item scope: `https://my-operations-center.com/cjoc/job/my-team/job/dev/serviceAccounts/my-sa/api/`
View group members and manage group membership operations	Root scope: `https://my-operations-center.com/cjoc/groups/my-group/api/`
View group members and manage group membership operations	Item scope: `https://my-operations-center.com/cjoc/job/my-team/job/dev/groups/my-group/api/`

Examples

The following examples demonstrate common service account workflows using the REST API.

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 actually run.
Replace username:apiToken with your credentials (either your username and API token, or a service account name and token with appropriate permissions).
POST requests to REST API endpoints do not require a CSRF crumb when authenticated with service account tokens.

Create and use a service account

This example creates a service account in a folder, generates 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:

curl -X POST -u username:apiToken "https://my-operations-center.com/cjoc/job/my-team/job/dev/serviceAccounts/createServiceAccount?name=bot"▼

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

curl -u username:apiToken \
  --data-urlencode "description=For REST API access" \
  --data-urlencode "expiration=30d" \
  "https://my-operations-center.com/cjoc/job/my-team/job/dev/serviceAccounts/bot/createToken"▼

If successful, the response returns a JSON document with the token ID and password:

{
  "id": "12345678-90ab-cdef-1234-567890abcdef",
  "password": "cloudbees_ci_sa_abc123def456789012345678901234ef"
}▼

Copy the password value; it cannot be retrieved later. The id can be used to delete the token.

Verify the service account token is working using the whoAmI endpoint:
```
curl -u "my-team/dev/bot:cloudbees_ci_sa_abc123def456789012345678901234ef" "https://my-operations-center.com/cjoc/whoAmI/api/json?tree=name,authorities"▼
```
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 RBAC group in the my-team/dev folder:

curl -X POST -u username:apiToken "https://my-operations-center.com/cjoc/job/my-team/job/dev/groups/build-managers/addServiceAccount?name=my-team/dev/bot"▼

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

curl -X POST -u "my-team/dev/bot:cloudbees_ci_sa_abc123def456789012345678901234ef" "https://my-operations-center.com/cjoc/job/my-team/job/dev/job/my-job/build?delay=0sec"▼