Authenticate with client credentials

You can authenticate an external system against the automation orchestrator API by using the OAuth 2.0 client credentials grant flow.

Before you begin

A project administrator has created a service account and a credential, and has provided you with the client ID and client secret.
The external system has network access to the automation orchestrator API.

About this task

This flow enables machine-to-machine authentication without interactive user login. The external system sends its client credentials to the token endpoint and receives a short-lived JWT access token for subsequent API calls.

Procedure

Send a POST request to the token endpoint with the client credentials.
You can provide credentials in two ways:

Option 1: Form-encoded body

Include the client_id and client_secret as form-encoded parameters in the request body:
```
$ curl -X POST \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials&client_id=client_id&client_secret=client_secret" \
    https://orchestrator_host/api/v1/auth/token
```
Option 2: HTTP Basic authentication

Encode the credentials as client_id:client_secret in Base64 and pass them in the Authorization header (RFC 6749 section 2.3.1):
```
$ curl -X POST \
    -H "Authorization: Basic $(echo -n 'client_id:client_secret' | base64)" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials" \
    https://orchestrator_host/api/v1/auth/token
```
Where:
- client_id is the service account's client ID, for example nx_sa_7kx9m2p4q1w3n5v8.
- client_secret is the service account's client secret, provided at creation time.
- orchestrator_host is the hostname of your automation orchestrator instance.
Extract the access_token from the JSON response:
```
{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6Im5leHVzLTEifQ...",
  "token_type": "Bearer",
  "expires_in": 900
}
```
The expires_in value indicates the token's lifetime in seconds. The default is 900 seconds (15 minutes), but this value is configurable by the administrator. No refresh token is issued.
Use the access token as a Bearer token in the Authorization header for subsequent API requests:
```
$ curl -H "Authorization: Bearer access_token" \
    https://orchestrator_host/api/v1/projects/project_id/workflows
```
Replace access_token with the token value from the previous step.

Results

Confirm that the API returns a successful response. A 200 OK status code indicates that the token is valid and the service account has the required permissions for the requested resource.
If you receive a 403 Forbidden response, the service account does not have the required RBAC role for the requested action. Contact the project administrator to assign the appropriate role. For more information, see Assign RBAC roles to a service account.

Service account authentication error reference

Service account authentication can fail because of token expiration, incorrect credentials, or a disabled account. This reference covers error responses, expiration behavior, and troubleshooting steps.

Handle token expiration

Service account access tokens have a limited lifetime, as specified by the expires_in value in the token response. When the token expires, subsequent API requests return 401 Unauthorized.

To continue making API calls, request a new token by repeating the client credentials grant flow. No refresh tokens are issued for service accounts. Your integration should implement one of the following strategies:

Proactive renewal: Track the token's expiration time and request a new token before the current one expires.
Reactive renewal: Catch 401 Unauthorized responses and request a new token before retrying the failed request.

Error responses

All token endpoint errors use the application/problem+json format (RFC 9457). The token endpoint returns a generic 401 error for all authentication failures to prevent client ID enumeration.

The following conditions result in a 401 error:

The client ID is not recognized.
The client secret does not match the current or previous (non-expired) secret hash.
The service account status is disabled.
The service account has been deleted.
The credential status is disabled.
The credential has expired.

Troubleshooting

If authentication fails, check the following:

Confirm that the client_id and client_secret values are correct and that no extra whitespace or line breaks were introduced during copy.
Verify that the service account status is active and that it has not been disabled or deleted.
Check that the credential has not expired. The service_accounts.credential_max_lifetime_days setting controls the maximum lifetime. The default is 180 days. To view or change this value, expand System Administration in the navigation sidebar, click Settings, then open the Authentication tab. System Administration and Settings appear only if you have the setting:read permission. If the credential has expired, create a new credential or rotate the existing one to reset its expiration.
Ensure that the grant_type parameter is set to client_credentials.
Check that the Content-Type header is set to application/x-www-form-urlencoded.
Confirm that the external system has network access to the automation orchestrator API.