API

Last updated 3 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.

Auth

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.

Authentication

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:

Key

Value

Description

type

api-key

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

key

Your API key

secret

Your API secret

Example:

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.

Example:

{
"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.

Errors

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:

Property

Description

Example

code

The HTTP response code

400

name

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

BadRequest

message

An explanation of the error

Invalid authentication information

errors

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

Example:

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

Pagination

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:

Parameter

Description

$limit

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

$skip

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

Resources