Quick Start

Getting started with Duckity is quite simple. Head over to Duckity's Dashboard and log in using your favorite method. If it's your first time logging in, your account will be automatically created.

Create an Application

Duckity is divided into one or more applications within your account. You create one application per project in which you want to integrate Duckity. To create a new application, press on the yellow + New Application button at the top right corner of the screen.

Once you've set the name of it, press on the ✓ Create Application button. Congratulations! You now have your first application created.

Additionally, in case your application is a web app, you can set up the CORS origins to fit your application's origins. For example, if you'll be protecting the login form of your app hosted at https://example.com/login, add https://example.com (scheme and host, no path) to your app's origins. If your application is not a web app, you can leave the CORS origins empty.

Create a Policy

Applications commonly have multiple features that need to be protected. For example, you may have a signup form and a login form with different protection needs. For each, you'll create one policy with settings tuned to each feature's specific needs.

Each application needs at least one policy to work. To create your first one, press the + Create Policy button.

Set the name to the name of the feature you'll be protecting, like "Sign-up Form" or "Add Friend". This is for you to recognize it later, it won't be displayed to your users. Once you're done filling it, press on ✓ Create Policy.

Copy your policy's ID using the button at the top right corner, that's all you'll need to integrate it into your application.

Don't worry about all the settings displayed for now, you'll learn to tune them later.

Install a Client SDK

To integrate your policy into your application, you'll need to install a client SDK in your client and validate solution tokens from your server. This is very simple to do and will take you little to no time.

Run the following line in your terminal to install the Duckity SDK.

npm install @duckity/js

Then import it in your code:

import * as duckity from "@duckity/js";

Once you've imported the SDK, solve a challenge like follows:

async function handleSubmit(e) {
    e.preventDefault();
    const solution: string = await duckity.solve(POLICY_ID);
    // Send it to your backend.
}

Send that solution token to your backend server. It's usually a good idea to send it in a X-Duckity-Solution header in your request, for example

await fetch("/api/login", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "Accept": "application/json",
        "X-Duckity-Solution": solution
    },
    body: JSON.stringify({
        login: username,
        password: password,
    }),
});

You can read about advanced usage in the SDK's documentation page:

JavaScript

Integrate Duckity into your application using the JavaScript SDK.

Install a Server SDK

Once you have a solution token in your server, validating it is quite easy.

Run the following line in your terminal to install the Duckity SDK.

npm install @duckity/js

Then import it in your code:

import * as duckity from "@duckity/js";

To validate the solution token, use duckity.validate().

let isValid = await duckity.validate(
    solution,             // The solution token submitted by the client.
    clientIp,             // The IP address of the client that submitted the solution.
    applicationSecret,    // Your application's secret. Get it from the dashboard.
    policyId,  // The policy ID used to generate the challenge.
);

That's it! If the solution is not valid, reject the request with an error. Otherwise, proceed to process the rest of the request.

Next Steps

Once you have successfully integrated duckity into your application, you're done with the code part. The behavior of challenges issued is fully customizable from the Duckity dashboard. Almost every configuration can be easily understood by their dashboard description. However, to learn how to combine settings to produce a more powerful setup, check out the following guide. It goes configuration by configuration to teach you how to configure the parameters you need to suit your application's needs.

Tune a Policy

Learn how to tune your policies to better protect your application while enhancing your users' experiences.