Programmatic authentication with client credentials

Overview

This guide explains how to create and use client credentials for automating access to NGINXaaS APIs. Client credentials enable automation tools such as CI/CD pipelines to manage your deployments, configurations, and certificates without requiring user login.

To authenticate, you exchange your client credentials (client ID and secret) for a short-lived access token from the NGINXaaS token endpoint. This access token is then used in the Authorization header of your API requests. Access tokens have limited validity, after which you’ll need to request a new one using the same credentials.

Client credentials are scoped to an organization and expire after a set period (up to 1 year, 6 months recommended).

Before you begin

• You must be logged in to the NGINXaaS Console.

Create client credentials

Follow these steps to create a new client credential through the NGINXaaS console:

1. Log in to NGINXaaS Console.
2. Select Settings > Client Credentials from the left navigation menu.
3. Select + Add Client to create a new credential.
4. Enter a unique name for your client in the text field that appears.
5. Choose an expiration date (maximum 1 year from today; 6 months is recommended). This setting is immutable after creation.
6. Select Create.
7. A popup window displays your client secret.

Important: Store Your Client Secret Securely

The client secret appears only once. Save it immediately in a secure location, such as a password manager or secrets vault.

Your client credentials can access the following APIs:

• Certificates API
• Configs API
• Deployments API

Client limits

Organizations are limited to a maximum of 10 client credentials. To request an increase to this limit, contact the (NGINX Support team)(https://frontdoor-test-docs.nginx.com/previews/docs/2052/nginxaas/google/get-help/support/).

Retrieve client information

Follow these steps to view information about your clients:

1. Log in to NGINXaaS Console.

2. Select Settings > Client Credentials from the left navigation menu.

3. You can see all the available client credentials for your organization in the Client Credentials page. The table shows the following metadata for each credential:

   • Client Name
   • Client ID
   • Token Endpoint
   • Date Created
   • Expires On

4. Check the expiration status indicator next to Expires On:

   • Green dot: Credential is active and valid
   • Red dot: Credential has expired

Client secrets are not displayed after creation. If you need to use credentials again, you must have saved the secret when you initially created the client.

Deleting client credentials

Follow these steps to delete a client credential:

1. Log in to NGINXaaS Console.
2. Select Settings > Client Credentials from the left navigation menu.
3. Locate the credential to delete in the table.
4. Select the three vertical dots icon (⋮) at the end of the row.
5. Select Delete from the menu.

After deletion:

• Existing access tokens continue to work until they expire (1 hour from issuance)

Expired credentials are not automatically removed. You must manually delete credentials that are past their expiration date.

Using client credentials for authentication

Learn how to obtain and use access tokens from your client credentials to authenticate API requests.

Exchange credentials for an access token

Use the client credentials to obtain an access token from the token endpoint.

Endpoint: POST https://<GEO>.api.nginxaas.net/api/v1/marketplace/auth/token

Example using cURL:

curl -X POST "https://<GEO>.api.nginxaas.net/api/v1/marketplace/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "<CLIENT_ID>",
    "client_secret": "<CLIENT_SECRET>",
    "grant_type": "client_credentials"
  }'

Response:

{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use the access token

Include the access token in the Authorization header when making API requests.

Example:

curl -X GET "https://<GEO>.api.nginxaas.net/api/v1/deployments" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Access token validity

• Duration: Access tokens are valid for 1 hour from issuance
• Reauthentication: When a token expires, request a new one using the same client credentials, if the client credentials are still active
• Scope: Tokens are also scoped to the organization associated with the client credentials

Security best practices

• Store secrets securely: Store client credentials in a secure place
• Delete unused credentials: Remove clients that are no longer needed
• Follow the recommended expiration: Avoid using clients with a very long expiration, a good default to begin with is 6 months

Troubleshooting

Common issues when authenticating with client credentials and how to resolve them.

Invalid or expired credentials

If you attempt to authenticate with invalid or expired credentials, you will receive a 401 Unauthorized response. In this case:

• Verify your client ID and secret are correct
• Check if the client has expired
• Create new credentials if necessary

Example error response:

{
  "error": "unauthorized",
  "error_description": "token is expired/invalid"
}

Forbidden APIs

Client credentials can only access the Certificates, Configs, and Deployments APIs. Attempting to access any other API with client credentials returns a 403 Forbidden response. In this case:

• Verify you are using the correct API endpoint
• Ensure the API is one of the supported resources (Deployments, Configs, or Certificates)

Example error response:

{
  "error": "forbidden",
  "error_description": "Client credentials do not have permission to access this resource"
}

Quick reference

What’s next

Manage your NGINXaaS deployments

Manage your NGINX configurations