The Protection API provides a decision to allow or block any HTTP request based on its properties.

Validation requests should be sent to the Protection API by modules installed on a component of your backend infrastructure (CDN, load balancer, application server, etc).

API responses

API calls return HTTP status codes and headers that you can use inside your module or application.

API status codes

Module behavior must change depending of the following API response code:

API status codesMeaningDescriptionInstructions to follow
400Invalid or missing credentialsThe request was rejected by the API due to the API key being invalid or missing from the payloadCheck that the API key inserted in the payload is the server-side key provided on your dashboard. Contact our support if the problem persists.
401/403Blocked requestThe current request should be blockedThe module should stop processing the request and forward a response to the client with properties returned by the API. See the Handling API response headers section below for more details.
301/302Redirected requestThe current request should be redirected to a specific URLThe module should redirect the client to a URL that will be added to the Location header found on the API response.
200Allowed requestThe hit should be allowedThe module should let the application proceed with the request.

πŸ“˜

Handling unsupported HTTP status codes

Status codes that are not listed in the table above should be ignored by the module and the request should be let through.

πŸ“˜

Validating the X-DataDomeResponse header

The module must validate that the HTTP status code returned by the API has the same value as the X-DataDomeResponse header. If not, the module must ignore it and allow the request as if it received a 200 response.

Handling API response headers

The module must merge certain headers coming from the API depending on the decision it made.

Headers to add to the client request and response

  • The API response will include a X-DataDome-request-headers header that lists the names of the headers to pick up from itself and add to the client request before it reaches the origin.
  • It will also include a X-DataDome-headers header that lists the names of the headers to pick up from itself and add to the response that will be sent to the client.

🚧

Some headers must not be sent back to the client

Clients like web browsers, web views or mobile applications should never receive the following headers:

  • X-DataDome-request-headers
  • Any header that was listed by X-DataDome-request-headers
  • X-DataDome-headers
  • Here is an example of response headers sent by the API:
X-DataDome-request-headers: X-DataDome-botname X-DataDome-botfamily X-DataDome-isbot
X-DataDome-botname: Crawler fake Google
X-DataDome-botfamily: bad_bot
X-DataDome-isbot: 1
X-DataDome-headers: Set-Cookie Pragma X-DataDome Cache-Control
Set-Cookie: datadome=some-value; Domain=domain.com; Path=/; Expires=Wed, 13 Jan 2021 22:23:01 GMT;
Pragma: no-cache
X-DataDome: protected
Cache-Control: no-cache
X-DataDomeResponse: 403
  • Here is what the module should add to the client request:
X-DataDome-botname: Crawler fake Google
X-DataDome-botfamily: bad_bot
X-DataDome-isbot: 1
  • Here is what the module should add to the client response:
Set-Cookie: datadome=some-value; Domain=domain.com; Path=/; Expires=Wed, 13 Jan 2021 22:23:01 GMT;
Pragma: no-cache
X-DataDome: protected
Cache-Control: no-cache

πŸ“˜

JSON responses and the X-DD-B header

When the API blocks a request that had a Content-Type: application/json header, then it will reply with a JSON response too unless the targeted endpoint was configured to return an HTML response on your dashboard.

The API will always include an X-DD-B header to JSON responses, which will be listed by X-DataDome-headers, meaning it must be added to client responses.

Additional features to support

Session by header

Here are the prerequisites to support the session by header feature available on the JS Tag.

  • If an incoming HTTP request includes a X-DataDome-ClientID header, its value should be picked for the ClientID field instead of the datadome cookie.

When session by header is enabled on the JS Tag, it will expect to get the new cookie value from the X-Set-Cookie header instead of the standard Set-Cookie header.

  • To enable that response header, add the following header on the HTTP request that will be sent to DataDome's Protection API: X-DataDome-X-Set-Cookie: true

Here is an example of implementation in Lua:

if request_headers['x-datadome-clientid'] ~= nil then  
   body['ClientID'] = request_headers['x-datadome-clientid']  
   datadomeHeaders["X-DataDome-X-Set-Cookie"] = "true"  
else  
   body['ClientID'] = clientId  
end

Size limits for payload fields

❗️

Total size limit (24 kB)

API servers won't accept incoming request payloads that are larger than 24 kB.
Each field must be truncated according to the limits defined in the table below.

❗️

Truncation order

Fields with an asterisk (*) should be truncated from the end.

FieldsLimit per field (in bytes)
Key, APIConnectionState, AuthorizationLen, CookiesLen, IP, Method, ModuleVersion, Port, PostParamLen, Protocol, RequestModuleName, TimeRequestUnlimited
SecCHDeviceMemory, SecCHUAMobile, SecFetchUser8
SecCHUAArch16
SecCHUAPlatform, SecFetchDest, SecFetchMode, ClientID32
ContentType, SecFetchSite64
AcceptCharset, AcceptEncoding, CacheControl, ClientID, Connection, From, GraphQLOperationName, Pragma, SecCHUA, SecCHUAModel, TrueClientIP, UserID, X-Real-IP, X-Requested-With128
AcceptLanguage, SecCHUAFullVersionList, Via256
Accept, HeadersList, Host, Origin, ServerHostname, ServerName, XForwardedForIP*512
UserAgent768
Referer1024
Request2048

❗️

Empty header values

If a header value is empty, the corresponding field shouldn't be sent with the payload.

Language
Click Try It! to start a request and see the response here!