API Client Secrets

Published by Andrew Pantalone on November 6, 2024

Existing ClientSecrets defined directly on the ApiClient will continue to function, but may be phased out at some point in the future. We highly encourage switching out any existing ClientSecrets with new ones, you can do this with no downtime as described in the Rotating API Client Secrets section.

Overview

API Client Secrets offer a flexible and secure way of managing client credentials authentication for OrderCloud API Clients. Sellers can now create up to 10 secrets per API Client. Expiration dates can optionally be set for each secret. Token requests that submit an expired secret will fail. By controlling the generation of the secret, allowing multiple secrets per API Client, and allowing optional expiration dates for secrets, OrderCloud ensures the cryptographic strength of the secrets and gives seller administrators a finer level of control over client authentication. This also permits the rotation of client secrets with zero application downtime. Periodic rotation of client secrets is considered a security best practice.

Creating an API Client Secret

When a seller creates a secret, OrderCloud will generate a random, cryptographically secure string in Base-64 format. Below is a sample response from POST v1/apiclients/{apiClientID}/secrets

1{ 
2   "ID": "7SMyi3XT2UC2NsDL7NhUzw",
3   "Name": "SampleAPISecret",
4   "Expiration": "2024-06-21T19:02:09.9419824+00:00",
5   "ClientSecret": "JtPEASFGvtvDp3Fx9dnqO9XYnGNPKDZXQaR9ExSx6/JsIU8N1T5oRkcJqUIw0DXEC1FtS7oNA7cV+zCq7e+SiIwuD4Jsa+K67LDNYIReGL0GvNHyULXsWeyVU2Y5OK3QHsf0jjC8ybYgzyWXTJ6slrt2OaeACam5fcUXpUTVZvHqzvdRGDGQX7gDz8qVUtKOK8g6cGA1jXCsUrDfVYx4zlpTMEqfmVVAP3JbwUu3t0JYGnSsYnzorEe+yZL1ssgGH0gZCcIKAgyUQaYl8tDvuz4YnEkUmnynpRt5dfQk2YLv80ORg7jRPOwJAAZAxl//+w3Nr1rREEHf4LgdsoF8bA=="
6}

The value for the client secret is only available once, in the response to the POST operation. It cannot be retrieved afterward.

A valid client secret must be provided during authentication flows when requesting a token from an API Client that has client secrets defined, even if the grant type is not client credentials (e.g. password grant, refresh token). Generally speaking, you should not have a ClientSecret defined for an API Client that is used for customer/browser authentication.

Rotating API Client Secrets

To rotate a client secret for an API Client, simply create a new API Client Secret for that API Client, and update any references in your code to point to the new secret. Since the feature allows multiple secrets to work concurrently for each client, the old secret will continue to work until it is deleted or until it expires, if an expiry has been set. This allows OrderCloud consumer applications to continue to function until they are updated to submit the new secret. This overlap allows for key rotation with no downtime.

New Resource: `ApiClientSecret`

1"ApiClientSecret": 
2{
3  "ID": "",
4  "Name": "",
5  "Expiration": ""2024-11-04+00:00"
6}

New Endpoints

GET v1/apiclients/{apiClientID}/secrets/{apiClientSecretID}
GET v1/apiclients/{apiClientID}/secrets
POST v1/apiclients/{apiClientID}/secrets
- Expiration is optional, if no expiration is defined, the secret will never expire
- Response includes a new ClientSecret that cannot be retrieved again
PATCH v1/apiclients/{apiClientID}/secrets/{apiClientSecretID}
- only Name, ID and Expiration can be modified
DELETE v1/apiclients/{apiClientID}/secrets/{apiClientSecretID}

Still have questions?
Ask in our Community Channel