Using the Colorlab API
Please follow these practices when implementing the Colorlab API:
- All API calls should be implemented on the server side for security purposes;
- API calls should never be triggered from the client side (for example with an AJAX call from the browser), as such implementations can be easily exploited;
- The amount of API calls should be limited to a reasonable amount to prevent rate limiting (see Rate Limiting);
- Errors returned from the Colorlab API should be handled gracefully by your application;
- API calls should be implemented apart from existing flows in which your end users are involved. This will prevent errors or downtime of the Colorlab API impacting these flows. For example: pushing order data to Colorlab should happen after orders are placed, preferably in a spreaded way (e.g. using a cron-job) to prevent Rate Limiting when a lot of orders are placed at the same time.
As ignoring these practices could result in disabling your API keys, please feel free to contact Colorlab Support for assistance about how to implement your specific use-case.
For every request to the API, you need to send 3 custom HTTP headers:
|The shop ID of your shop (displayed in the |
|Your API key.|
|The signature generated on your side using an API secret. The signature is used to validate your request.|
Every time you request an API endpoint, you need to send along a signature using the
X-Colorlab-Api-Signature header. This signature guarantees that the request is valid and not accessible by other parties.
The signature is calculated on a per-endpoint basis. Every calculation involves your API secret.
Never send your API secret to the endpoint, only use it to generate the signature. This makes sure requests can only originate from the source which knows the API secret.
Generating API signatures
Each API endpoint requires generating a header
X-Colorlab-Api-Signature. This signature is a
string generated using:
The endpoint requires following verification string
Store ID +
Template ID. The Store ID is equal to
634fc08da68c799b9429571e and the Template ID is equal to
- resulting verification string:
You need to compute a sha256 HMAC signature with the verification string and your API secret in code, or using an online generator like https://www.freeformatter.com/hmac-generator.html.
If your API secret is
a084db82-f995-44cd-98ff-837be3c9af3f, this will result in following HMAC:
You need this value for the
X-Colorlab-Api-Signature header when sending requests to the API.
You can find your
Store ID on the settings page in the Colorlab Console.
The Colorlab API applies rate limiting to all endpoints following the leaky bucket algorithm.
Exceeding rate limits
You can make a maximum number of requests per minute. Each request counts equally, regardless of how much or how little data is returned. All requests that are made after rate limits have been exceeded are throttled and an
HTTP 429 Too Many Requests error is returned.
When implementing the API, you should take into account that limits apply, and prevent exceeding these limits by:
- limiting the amount of requests at a time
- add error handling that allows you to catch these errors if they do occur
How quota's are communicated
Each call to the API returns following response headers:
|Response header name||Example value||Description|
|You are allowed to execute 30 API requests in 1 minute|
|You have 17 requests remaining in the current window|
|The remaining time in the current window in seconds|
Requests will succeed again after enough requests have emptied out within the current window.