1. Authentication

API client secrets

Note

Legacy support and migration

While existing ClientSecrets defined directly on ApiClients remain functional, they may be deprecated in the future. We recommend migrating to the new API Client Secrets system, which can be done without service interruption using the secret rotation process.

Overview

API Client Secrets provide enhanced security and management capabilities for OrderCloud API Clients. Key features include:

  • Multiple secrets per API Client (up to 10)
  • Optional expiration dates
  • Automatic secret generation
  • Zero-downtime rotation support

These features enable:

  • Strong cryptographic security
  • Fine-grained authentication control
  • Seamless secret rotation
  • Security best practice implementation

Secret creation process

The system generates cryptographically secure random strings in Base-64 format. Example response from POST v1/apiclients/{apiClientID}/secrets:

json
{
  "ID": "7SMyi3XT2UC2NsDL7NhUzw",
  "Name": "SampleAPISecret",
  "Expiration": "2024-06-21T19:02:09.9419824+00:00",
  "ClientSecret": "JtPEASFGvtvDp3Fx9dnqO9XYnGNPKDZXQaR9ExSx6/JsIU8N1T5oRkcJqUIw0DXEC1FtS7oNA7cV+zCq7e+SiIwuD4Jsa+K67LDNYIReGL0GvNHyULXsWeyVU2Y5OK3QHsf0jjC8ybYgzyWXTJ6slrt2OaeACam5fcUXpUTVZvHqzvdRGDGQX7gDz8qVUtKOK8g6cGA1jXCsUrDfVYx4zlpTMEqfmVVAP3JbwUu3t0JYGnSsYnzorEe+yZL1ssgGH0gZCcIKAgyUQaYl8tDvuz4YnEkUmnynpRt5dfQk2YLv80ORg7jRPOwJAAZAxl//+w3Nr1rREEHf4LgdsoF8bA=="
}
Important

  • Client secret values are only available in the creation response
  • Subsequent retrieval is not possible
  • Client secrets are required for all authentication flows when defined
  • Avoid using client secrets for customer/browser authentication clients

Secret rotation implementation

The rotation process enables seamless secret updates:

  1. Create new API Client Secret
  2. Update application code references
  3. Previous secret remains valid until:
    • Manual deletion
    • Expiration date reached

This overlap period ensures continuous application operation during updates.

API client secret resource

Resource structure:

json
{
  "ID": "",
  "Name": "",
  "Expiration": "2024-11-04+00:00"
}

Available endpoints

  • GET v1/apiclients/{apiClientID}/secrets/{apiClientSecretID}

    • Retrieves specific secret metadata

  • GET v1/apiclients/{apiClientID}/secrets

    • Lists all secrets for an API client

  • POST v1/apiclients/{apiClientID}/secrets

    • Creates new secret
    • Optional expiration date
    • Returns one-time secret value

  • PATCH v1/apiclients/{apiClientID}/secrets/{apiClientSecretID}

    • Updates Name, ID, or Expiration
    • Cannot modify secret value

  • DELETE v1/apiclients/{apiClientID}/secrets/{apiClientSecretID}

    • Removes secret from system
If you have suggestions for improving this article, let us know!