Cryptlex Web API
The Cryptlex Web API provides programmatic access to our services and adheres to the RESTful design principles. We strive for clear communication and ease of use for both experienced and novice developers.
The key features of the Web API are:
- All requests must be made over HTTPS for secure communication.
- All URLs are resource-oriented to help with predictably navigating the API.
- Responses consistently use JSON format, even for error messages.
- Standard HTTP status codes indicate success or failure, and detailed error messages help identify and resolve issues.
Versioning
All API requests are versioned using the major version prefixed by a 'v' in the URL, e.g. v1, v2, v3. The latest supported version is v3 (3.x.x).
We follow Semantic Versioning. Given a version number MAJOR.MINOR.PATCH, the version is incremented in the following manner:
- MAJOR version when we make incompatible/breaking API changes,
- MINOR version when we add functionality in a backward-compatible manner, and
- PATCH version when we make backward-compatible bug fixes.
When we introduce breaking changes to the API, we will release a new versioned URL endpoint. You can refer to our changelog for changes made to date.
Errors
The API uses standard HTTP status codes to indicate the success or failure of the API call. All errors contain 4xx or 5xx status codes in the response header. The body of the response will contain the error message in the following format:
{
"message": "Email address is already taken!",
"code" : "DUPLICATE_FIELD_VALUE" // conditional
}
Rate Limiting
A single IP address can make a maximum burst of 50 requests per 5-second window, regardless of authentication. If we observe patterns of abuse, the IP address may be temporarily or permanently blacklisted.
Rate limit status can be checked in the returned HTTP headers of any API request:
| Header | Description |
|---|---|
| X-Rate-Limit-Limit | The rate limit period (eg 1m, 12h, 1d). |
| X-Rate-Limit-Remaining | The number of requests remaining in the current rate limit window. |
| X-Rate-Limit-Reset | The UTC date and time when the limits reset. |
Related Resources
Resources in the API relate to one another. For example, a license relates to a user, a reseller, and an organization. By default, a response contains only the requested resource, along with the IDs of its related resources (such as userId). A related resource can be fetched separately using its ID, e.g. GET /v3/users/{id}.
Use the include query parameter, where available, to embed full related resources in a single request. For example, to return each license with its full user object:
GET /v3/licenses?include=user
The include parameter accepts a comma-separated list of related resources. Including more resources may result in larger responses and longer response times.
GET /v3/licenses?include=user,reseller
Your access token must have read permission for every related resource you include, e.g. include=user requires the user:read permission. Requesting a resource you are not authorized to read fails with a 403 Forbidden response. Providing an unsupported include value fails with a 400 Bad Request response.