Create a service account

You can create a service account in a project to provide an external system with credentials for programmatic API access.

Before you begin

You have the service_account:create permission in the target project, or you are a project administrator.
At least one project exists in automation orchestrator.

About this task

Creating a service account is a two-step process: you create the service account, and then you create one or more credentials for it. The credential contains the client ID and client secret that the external system uses to authenticate.

Procedure

Send a POST request to the service accounts endpoint.

Include the project_id of the project where you want to create the service account:

$ curl -X POST \
    -H "Authorization: Bearer access_token" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "service_account_name",
      "description": "description",
      "project_id": "project_id"
    }' \
    https://orchestrator_host/api/v1/service_accounts

Where:

access_token is your personal access token or session token.
service_account_name is a human-readable name for the service account, for example CI Pipeline or ITSM Integration.
description is an optional description of the service account's purpose.
project_id is the UUID of the target project.
orchestrator_host is the hostname of your automation orchestrator instance.

Example response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "CI Pipeline",
  "description": "Service account for Jenkins CI integration",
  "status": "active",
  "project_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
  "last_authenticated_at": null,
  "created_by": "12345678-abcd-efab-cdef-1234567890ab",
  "created_at": "2026-07-02T14:30:00Z",
  "updated_at": "2026-07-02T14:30:00Z",
  "labels": {}
}

Record the id value. You need it to create a credential in the next step.

Create a credential for the service account.
Send a POST request to the credentials endpoint, replacing service_account_id with the id from the previous step:
```
$ curl -X POST \
    -H "Authorization: Bearer access_token" \
    -H "Content-Type: application/json" \
    -d '{
      "credential_type": "client_credentials"
    }' \
    https://orchestrator_host/api/v1/service_accounts/service_account_id/credentials
```
You can optionally include an expires_at timestamp (ISO 8601 with timezone) to set a custom expiration for the credential. If you omit expires_at, automation orchestrator sets the expiration automatically based on the configured maximum credential lifetime.

Example response:
```
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "service_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "credential_type": "client_credentials",
  "identifier": "nx_sa_7kx9m2p4q1w3n5v8",
  "client_secret": "generated-plaintext-secret",
  "status": "active",
  "grace_period_seconds": 3600,
  "expires_at": "2026-12-29T14:31:00Z",
  "old_secret_valid_until": null,
  "last_used_at": null,
  "created_by": "12345678-abcd-efab-cdef-1234567890ab",
  "created_at": "2026-07-02T14:31:00Z"
}
```
Warning:

The client_secret is displayed exactly once in this response. You cannot retrieve the secret after this point. If you lose the secret, you must rotate to a new one.

The expires_at value shows when the credential expires. An administrator can configure the maximum credential lifetime. The default is 180 days. The valid range is 0 to 730 days, where 0 means the credential never expires.
Record the identifier (client ID) and client_secret values from the credential response.
Store the client credentials securely, such as in a secrets manager or encrypted vault.
Share the client ID and client secret with the integration owner who configures the external system.

Results

Confirm the service account is displayed in the project's service account list with active status:

$ curl -H "Authorization: Bearer access_token" \
    https://orchestrator_host/api/v1/service_accounts

The response includes the new service account with "status": "active".

What to do next

Next steps: