Client Secret Rotation

This guide explains how to perform Client secret rotation—the process of updating the API credential secret generated when you create a new Project through the Bud Console.

📘

Note: This process can only be performed by the owner of the existing Client secret. You will need your existing secret to authorise the rotation, which will then generate a new secret that you must store securely.

Prerequisites

Before you begin, ensure you have the following credentials:

• Your existing API Key ID (Project ID).
• Your existing API Key Secret.

Step 1: Authenticate with your existing credentials

First, create an access token using your current credentials, just as you would when interacting with any other Bud API.

Execute the following request:

curl --request POST \
  --url https://api-sandbox.thisisbud.com/v1/oauth/token  \
  --header 'authorization: Basic [your basic auth]' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'x-client-id: [your project ID]' \
  --data grant_type=client_credentials

Step 2: Create a new secret

Using the access token and Project ID from the previous step, you can now generate a new secret.

Bud does not immediately invalidate your existing secret; this ensures you have zero downtime to execute the rotation on your application's side. You are required to include a label in the request body. This label (e.g., 2025 Jan Secret Rotation) helps you identify and manage your secrets later.

Execute the following request:

curl --request POST \
  --url https://api-sandbox.thisisbud.com/v1/client-secrets  \
  --header 'authorization: Bearer [your access_token]' \
  --header 'content-type: application/json' \
  --header 'x-client-id: [your project ID]' \
  --data '{ "label": "[your label here]" }'

Example Response:

{
  "operation_id": "v1_client_secrets_post",
  "data": {
    "client_secret_id": "xxxxxx",
    "client_secret": "yyyyyy"
  }
}

🚧

Security Warning: Make sure to store the new client_secret securely right away. Bud cannot retrieve this value, and it will not be shown to you again.

Step 3: List your API Key Secrets (optional)

You can list the secrets linked to your Project ID using the same credentials and token generated in Step 1.

Execute the following request:

curl --request GET \
  --url https://api-sandbox.thisisbud.com/v1/client-secrets  \
  --header 'authorization: Bearer [your access_token]' \
  --header 'x-client-id: [your project ID]'

This will return a list of your secrets, including their respective IDs and labels.

Example Response:

{
  "operation_id": "v1_client_secrets_get",
  "data": [
    {
      "client_secret_id": "9ad76f24-c2f3-45aa-8b49-1d4605abfd6c",
      "label": "default",
      "created_at": "2025-01-27T11:33:54+0000"
    },
    {
      "client_secret_id": "fd237257-f499-46cd-9e55-11b02af5f285",
      "label": "2025 Jan Secret Rotation",
      "created_at": "2025-01-27T14:07:19+0000"
    }
  ],
  "metadata": {
    "page": 0,
    "page_size": 1000,
    "results": 2
  }
}

Step 4: Rotate the secret on your application

At this point, both your old and new secrets are active and can be used to generate access tokens. This overlap allows you to safely deploy the new secret to your application without experiencing any downtime.

📘

Important: Verify that your application has been fully updated to use the new secret before deleting the old one. Bud cannot restore deleted secrets.

Step 5: Create an access token with the new secret

To proceed with the final cleanup, verify your new credentials by generating a new access token.

Execute the following request:

curl --request POST \
  --url https://api-sandbox.thisisbud.com/v1/oauth/token  \
  --header 'authorization: Basic [your NEW basic auth]' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'x-client-id: [your project ID]' \
  --data grant_type=client_credentials

Step 6: Delete the old secret

Now that your application is securely using the new secret, you can safely delete the old one from Bud.

In the request URI below, be sure to specify the OLD secret ID that you retrieved during Step 3.

Execute the following request:

curl --request DELETE \
  --url https://api-sandbox.thisisbud.com/v1/client-secrets/[the OLD secret ID] \
  --header 'authorization: Bearer [your access_token]' \
  --header 'x-client-id: [your project ID]'

If the deletion is successful, the Bud API will return a 204 response code with no content.

Step 7: Verify your old secret was deleted

To confirm that the old secret has been successfully removed, repeat Step 3. The resulting list should now only display the new secret currently generating your access tokens.