Rotate a service account secret

You can rotate a service account credential's secret to replace it with a new one.

Before you begin

A service account exists with at least one credential.
You have the service_account:rotate_secret permission, or you are a project administrator.
You know the service account ID and the credential ID. To find these values, list the credentials for the service account:
```
$ curl -H "Authorization: Bearer access_token" \
    https://orchestrator_host/api/v1/service_accounts/service_account_id/credentials
```

About this task

Rotation is useful for periodic credential hygiene, responding to a suspected compromise, or meeting compliance requirements. The client ID stays the same during rotation, so you only need to update the secret in your external systems. During the grace period, both the old and new secrets are accepted, so you can update external systems without downtime.

When you rotate a secret, the following sequence occurs:

Automation orchestrator generates a new secret and hashes it.
The current secret hash is moved to a temporary storage field.
The old secret remains valid until the grace period expires.
During the grace period, authentication attempts are verified against the new secret first, then the old secret.
After the grace period expires, only the new secret is accepted.

Setting the grace period to 0 means the old secret is rejected immediately after rotation.

Procedure

Send a POST request to the credential rotation endpoint:
```
$ curl -X POST \
    -H "Authorization: Bearer access_token" \
    -H "Content-Type: application/json" \
    -d '{
      "grace_period_seconds": grace_period
    }' \
    https://orchestrator_host/api/v1/service_accounts/service_account_id/credentials/credential_id/rotate
```
Where:
- access_token is your personal access token or session token.
- service_account_id is the UUID of the service account.
- credential_id is the UUID of the credential to rotate.
- grace_period is the number of seconds that the old secret remains valid after rotation. This value is optional. If you omit the request body, the credential's stored grace period is used (default: 3600 seconds / 1 hour). Valid range: 0 to 86400 seconds (24 hours).
- orchestrator_host is the hostname of your automation orchestrator instance.
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": "new-generated-plaintext-secret",
  "status": "active",
  "grace_period_seconds": 3600,
  "expires_at": "2026-12-29T14:30:00Z",
  "old_secret_valid_until": "2026-07-03T15:30:00Z",
  "last_used_at": "2026-07-01T10:15:00Z",
  "created_by": "12345678-abcd-efab-cdef-1234567890ab",
  "updated_by": "12345678-abcd-efab-cdef-1234567890ab",
  "created_at": "2026-06-15T09:00:00Z",
  "updated_at": "2026-07-03T14:30:00Z"
}
```
Warning:

The client_secret is displayed only in this response. You cannot retrieve the secret after this point. Record the new secret immediately.

The identifier (client ID) remains unchanged. Only the secret is replaced.

The old_secret_valid_until timestamp shows when the previous secret stops being accepted. The expires_at timestamp is reset to a new full lifetime based on the configured maximum credential lifetime. The default is 180 days. The valid range is 0 to 730 days, where 0 means the credential never expires.
Update the new secret in your external system's configuration.
Store the new secret securely, such as in a secrets manager or encrypted vault.

Results

Authenticate with the new secret to confirm it works:

$ curl -X POST \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials&client_id=client_id&client_secret=new_secret" \
    https://orchestrator_host/api/v1/auth/token

During the grace period, authenticate with the old secret to confirm it is still accepted.

After the grace period expires, authenticate with the old secret to confirm it is rejected.

Example: rotating a ServiceNow integration credential

The following example rotates the secret for a service account that a ServiceNow instance uses to call automation orchestrator, using a 2-hour grace period to avoid downtime.

Rotate the credential:

$ curl -X POST \
    -H "Authorization: Bearer access_token" \
    -H "Content-Type: application/json" \
    -d '{"grace_period_seconds": 7200}' \
    https://orchestrator_host/api/v1/service_accounts/service_account_id/credentials/credential_id/rotate

Record the new client_secret from the response.
In ServiceNow, update the connection credential for the automation orchestrator integration with the new secret.
Test the ServiceNow integration to confirm it authenticates with the new secret.

The old secret continues to work for any ServiceNow jobs that started before the update and cached the old credential. After 2 hours, only the new secret is accepted.