Service account API endpoints

You can create service accounts and their authentication methods, including tokens and OpenID Connect (OIDC) configurations, using the REST API. The API provides endpoints to create, delete, and list service accounts, tokens, and OIDC configurations, 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 following table.

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 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 a service account

This example creates 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"▼

Add a token to a service account

This example adds a token to the bot service account, verifies authentication, adds it to a group, and then uses it to trigger a build.

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 Role-Based Access Control (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"▼

Create an OIDC configuration

OIDC authentication uses a temporary JSON Web Token (JWT) from an OIDC identity provider (IdP) to authenticate a service account without requiring a long-lived token.

A service account supports multiple OIDC configurations, but CloudBees recommends defining a separate service account for each IdP or system if you want to manage permissions for each independently.

For details on how OIDC authentication works and how to configure it, refer to Configure OIDC authentication (CasC) or Add an OIDC configuration to a service account (UI).

This example creates an OIDC configuration for the bot service account in the my-team/dev folder.

curl -u username:apiToken \
  --data-urlencode "issuer=https://token.actions.githubusercontent.com" \
  --data-urlencode "subject=repo:my-org/my-repo:ref:refs/heads/main" \
  "https://my-operations-center.com/cjoc/job/my-team/job/dev/serviceAccounts/bot/createOIDC"▼

If successful, the response returns a JSON document with the OIDC configuration details:

{
  "id": "12345678-90ab-cdef-1234-567890abcdef",
  "issuer": "https://token.actions.githubusercontent.com",
  "subject": "repo:my-org/my-repo:ref:refs/heads/main"
}▼

The audience field appears in the response only when explicitly specified; otherwise, CloudBees CI uses the service account URL as the default.

The id can be used to delete the OIDC configuration later using the deleteAuthentication endpoint (the same endpoint used to delete tokens).