Last updated 5 months ago

The Didomi platform offers a standard REST API that you can use to manage all aspects of the platform. Its base URL is: https://api.didomi.io/v1/. Our API uses standard HTTP verbs (GET, POST, etc.) to retrieve or modify resources and standard HTTP error codes (4xx and 5xx) to communicate errors when they happen with detailed error information in the body. All standard HTTP clients are able to talk to our API without modifications. The API always responds in JSON, including for errors. The only exception are routes that also support different formats like reports and, even in that case, JSON is the default format unless otherwise specified.

This section will guide you through setting up an API client and using the main resources exposed by our API. You will also want to consult our complete API specification as a reference when using our API.

You will need an API key and secret to call our API. If you do not have an API key yet, reach out to support@didomi.io.


Authorization token

All HTTP requests to the API must be authorized with a JWT access token via bearer authentication. The access token must be sent in the Authorization header. Example:

curl -H "Authorization: Bearer <token>" https://api.didomi.io/v1/properties

All API requests must be made over HTTPS. Calls made over plain HTTP will get a 301 response redirecting to their HTTPS equivalent. Calls without a valid authorization token will fail with a 401 error code.


To generate an authorization token, send an HTTP POST request to https://api.didomi.io/v1/sessions with a JSON body containing the following values:






The type of authorization request (in this case, using an API key and secret)


Your API key


Your API secret


curl --request POST --url 'https://api.didomi.io/v1/sessions' --header 'content-type: application/json' --data '{"type": "api-key", "key": "<Your API key>", "secret": "<Your API secret>"}'

The response will contain an access_token property with the token you should use for authorizing further requests. If there is a problem authenticating you, a 400 error is returned.


"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ"

You can generate as many tokens as you want. Tokens will expire after 24 hours so, if you are running a long-term process, make sure to regenerate a new token regularly.


Didomi uses standard HTTP response codes to indicate that an API request is a success or a failure. In general, the codes act as follows:

  • 2xx codes indicate a success

  • 4xx codes indicate an error in the parameters sent to the server (e.g. the authentication information is invalid, a required parameter is missing, etc.)

  • 5xx codes indicate a Didomi server-side error (it should not happen but hey, we are human too!)

When an error happens, you can look at the JSON response body to find more about the reason. The body will be an object with the following properties:





The HTTP response code



The name of the error (tied to the response code)



An explanation of the error

Invalid authentication information


An array containing more errors if multiple errors have been batched together


"code": 400,
"errors": {},
"message": "Invalid authentication information",
"name": "BadRequest"


For GET / requests that list entities, the standard response includes the total number of entities available (total property), the number of returned entities (limit property) and the number of entities that have been skipped (skip property).

A standard response looks like this:

"total": 100,
"limit": 10,
"skip": 0,
"data": [

You can control this behavior and paginate the returned entities with the following query-string parameters:




Number of items to return (it usually has to be lower than 100)


Number of skipped items (ie offset of the first item to be returned)