Account Protect can be integrated into your backend through SDK packages that are available on multiple platforms.

📘
Prerequisites for Account Protect
Account Protect is separate from Bot Protect and is not available on your account by default.
Please contact your account manager to enable it.
This service requires a dedicated API key, which will be available on your dashboard once it is enabled.

Installation

The Account Protect SDK is distributed on multiple platforms:

Maven package for Java 11+ and Spring Boot 2.x
Maven package for Java 17+ and Spring Boot 3.x - compatible with Scala 2.12+
Npm package for Node.js 14 or newer
NuGet package for .NET 6
Packagist package for Symfony PHP (8.1+) applications
Packagist package for Laravel PHP (8.1+) applications
Pypi package for Python 3.8 +
Ruby gem for Ruby 3.2+
Go package for Go 1.18+

You can use one of the commands below to install the relevant package for your application:

npm i @datadome/fraud-sdk-node

dotnet add package DataDome.AspNetCore.Fraud.SDK

<!-- insert in the pom.xml file of the project -->
<dependency>
  <groupId>co.datadome.fraud</groupId>
  <artifactId>fraud-sdk-java</artifactId>
  <!-- <version>1.0.1</version> --> <!-- compatible with Spring Boot 2.x -->
  <version>2.3.0</version>          <!-- compatible with Spring Boot 3.x -->
</dependency>

libraryDependencies += "co.datadome.fraud" % "fraud-sdk-java" % "2.2.1"

pip install datadome-fraud-sdk-python

composer require datadome/fraud-sdk-symfony

# 1. add `datadome/fraud-sdk-laravel` to your project
composer require datadome/fraud-sdk-laravel
# 2. Generate an autoloader
composer dump-autoload
# 3. Edit `config/app.php` to add `DataDomeServiceProvider`
# config/app.php
use DataDome\FraudSdkLaravel\Providers\DataDomeServiceProvider;
[...]
 'providers' => ServiceProvider::defaultProviders()->merge([
 [...]
 DataDomeServiceProvider::class
 
# 4. publish `datadome.php` in the `config` folder
php artisan vendor:publish

gem install datadome_fraud_sdk_ruby

go get github.com/datadome/fraud-sdk-go-package

Usage

Using the SDK requires changes in your application to handle the recommendations provided by DataDome's Account Protect API.

Example for a custom event

package main

import (
  "log"
  "net/http"

  dd "github.com/datadome/fraud-sdk-go-package"
)

func customEventHandler(client *dd.Client) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        if r.Method == http.MethodPost {
            userID := "fake_user_id"
            isAuthenticated := true
            user := dd.CustomEventUser{
                User:            dd.User{ID: userID},
                IsAuthenticated: &isAuthenticated,
            }

            sessionID := "fake_session_id"
            createdAt := time.Now().Format(time.RFC3339)
            session := dd.Session{
                ID:        &sessionID,
                CreatedAt: &createdAt,
            }

            fieldType := dd.StringCustomFieldType
            isPii := false
            customFields := []dd.CustomField{
                {Name: "planType", Value: "premium", Type: &fieldType, IsPii: &isPii},
            }

            validate, err := client.Validate(r, dd.NewCustomEvent(
                email,
                "userAction",
                dd.CustomEventWithStatus(CustomEventSucceeded),
                dd.CustomEventWithContent("some content"),
                dd.CustomEventWithUser(user),
                dd.CustomEventWithSession(session),
                dd.CustomEventWithEventStatus(dd.CustomEventSucceeded),
                dd.CustomEventWithAccountType(dd.CustomerAccountType),
                dd.CustomEventWithIsEventCritical(false),
                dd.CustomEventWithCustomFields(customFields),
            ))
            if err != nil {
                log.Printf("error during validation: %v\n", err)
            }
            if validate.Action == dd.Allow {
                w.WriteHeader(http.StatusOK)
                return
            } else {
                http.Error(w, "denied by Account Protect API", http.StatusForbidden)
                return
            }
        } else {
            http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
        }
    }
}

func main() {
  client, _ := dd.NewClient("FRAUD_API_KEY")
  
  mux := http.NewServeMux()
  mux.HandleFunc("/custom", customEventHandler(client))
  
  _ = http.ListenAndServe(":8080", mux)
}

API reference

`CustomEvent`

The SDK exposes methods for login validation that require a CustomEvent instance to be sent to the Account protect API along with the client request itself.

Available properties for this event type are listed below:

Name	Description	Default Value	Possible Values	Optional
account	The unique account identifier used for the login attempt.		Any string value.	No
accountTarget	The account related to the action		Any string value.	Yes
accountType	Describe the type of the account		`guest`, `staff`,`external`,`partner`, `customer`, `merchant`, `vip`, `test`, `other`	Yes
authentication.mode	Authentication mode		biometric, mail mfa, otp, password, other	Yes
authentication.socialProvider	Authentication social provider		amazon, apple, facebook, github, google, linkedin, microsoft, twitter, yahoo, other	Yes
authentication.type	Authentication type		local, socialProvider, other	Yes
content	Any raw text		Any string value.	Yes
customFields	See dedicated custom fields section in the FAQ			Yes
eventName	Name of the custom event in camelCase		Any string value.	No
eventStatus	Status of the custom event		`attempted`, `succeeded`, `failed`, `expired`	Yes
isEventCritical	Define if the action is linked to a sensitive behavior.	`false`	A boolean value	Yes
partnerId	Identify the partner using the solution.		Any string value.	Yes
session.createdAt	Creation date of the session		Format ISO 8601 YYYY-MM-DDThh:mm:ssTZD	Yes
session.id	A unique session identifier from your system		Any string value.	Yes
user.address.city	City of the address		Any string value.	Yes
user.address.countryCode	Country of the address		Format ISO-3166-1-alpha-2	Yes
user.address.line1	Line 1 of the address		Any string value.	Yes
user.address.line2	Line 2 of the address		Any string value.	Yes
user.address.regionCode	Region code			Yes
user.address.zipCode	Zip code			Yes
user.createdAt	Creation date of the user		Format ISO 8601 YYYY-MM-DDThh:mm:ssTZD	Yes
user.description	Description or biography of the user		Any string value.	Yes
user.displayName	Display name of the user		Any string value.	Yes
user.email	Email of the user		Valid email address	Yes
user.externalUrls	External URLs of the user		An array of valid URL address (max 10 items)	Yes
user.firstName	First name of the user		Any string value.	Yes
user.id	A unique customer identifier from your system. It has to be the same for all other event sent		Any string value.	No
user.lastName	Last name of the user		Any string value.	Yes
user.phone	Phone of the user		E.164 format including + and a region code Example : example +33978787878	Yes
user.pictureUrls	Pictures of the user		An array of valid URL address (max 10 items)	Yes
user.title	Title of the user		mr, mrs, mx	Yes
user.dateOfBirth	Date of birth of the user		Format ISO 8601 YYYY-MM-DDThh:mm:ssTZD	Yes

Validation response

Validating a login event should result in a response that can include the following properties:

Name	Description	Possible values	Always defined
action	The recommended action to perform on the login attempt.	`allow`, `deny`, `challenge`, `review`	Yes
errors	A list of objects representing each error with details. Each object will have the properties listed below.
errors[i].error	A short description of the error.
errors[i].field	The name of the value that triggered the error.
eventId	Event identifier associated to this validate event.	A valid UUID.	Yes
message	A description of the error if the status is `failure` or `timeout`.	Invalid header / Request timed out...
reasons	A list of reasons to support the recommended action.	`brute_force`, `teleportation`
score	The level of confidence when identifying a request as coming from a fraudster. Only available in Ruby SDK 2.1.0+, Go SDK v1.1.0+, and Node.js SDK 2.0.0+	Integer

Options

Options can be applied to the SDK during its instantiation.

Option Name	Description	Default Value
endpoint	The endpoint to call for the Account Protect API.	`https://account-api.datadome.co`
timeout	A timeout threshold in milliseconds. When an API request times out, the SDK will allow it by default.	`1500`

You can find usage examples for each platform below:

const instance = new DataDome(apiKey, {
    timeout: 1500, 
    endpoint: 'https://account-api.datadome.co',
});

// appsettings.json

// The API key is always required, but can also be passed as
// an environment variable named DataDome__FraudAPIKey
"DataDome": {
    "FraudAPIKey": "----",
    "Timeout": 1500,
    "Endpoint": "https://account-api.datadome.co"
}

new DataDomeFraudService(datadomeFraudApiKey, 
                         DataDomeOptions.newBuilder()
                         .endpoint("https://account-api.datadome.co")
                         .timeout(1500)
                         .build()
  );

datadome_instance =  DataDome("FraudAPIKey", timeout=1500, endpoint="https://account-api.datadome.co")

val dataDomeFraudService = new DataDomeFraudService(datadomeFraudApiKey, 
                                                    DataDomeOptions.newBuilder()
                                                    .endpoint("https://account-api.datadome.co")
                                                    .timeout(1500)
                                                    .build()
                                                   )

// .env

DATADOME_FRAUD_API_KEY='----'
DATADOME_TIMEOUT=1500
DATADOME_ENDPOINT='https://account-api.datadome.co'

// .env

DATADOME_FRAUD_API_KEY='----'
DATADOME_TIMEOUT=1500
DATADOME_ENDPOINT='https://account-api.datadome.co'

datadome = DataDome.new(1500, 'https://account-api.datadome.co', config.logger)

client, err := dd.NewClient(
  "FRAUD_API_KEY",
  dd.ClientWithEndpoint("account-api.datadome.co"),
  dd.ClientWithTimeout(1500),
)

FAQ

What happens if there is a timeout on API request?

The SDK has been designed to have minimal impact on the user experience. If the configured timeout is reached, the SDK will cancel its pending operation and allow the application to proceed.

What happens if the API returns an error?

Errors and timeouts are handled the same way by the SDK: it will not interrupt the application and allow it to proceed.

What happens if my API key is incorrect?

Invalid keys are detected when calling the account protect API. The SDK will return an allow response to avoid blocking any login or registration attempt on the application. This response will also have a failure status and a message that describes the problem.

What are Custom Fields

Custom fields allow to send additional data. Up to 5 custom fields can be defined.

Each field is defined by the following

name	type	description	Required
name	string	name of the custom field	Yes
value	string		Yes
type	string	values: `Number`, `String`, `Phone`, `email`, `userId`, `IP`	No
isPii	boolean	`true`if value contains Personally Identifiable Information	No

Data type Phone must respect the E.164 format