Using the Server side SDK (sSDK)

Server Side SDKs (server-SDKs or sSDKs) are provided as a wrapper to direct HTTP calls to our API to help you verify tokens.

Using the Node.js sSDK

The Node.js sSDK is available on npm.

npm install @iocaptcha/server

package

Initializing the Api object

First, import the required objects from the @iocaptcha/server package.

import { Api } from "@iocaptcha/server";

Then, initialize the Api object with your endpoint's public and private keys.

const iocaptcha = new Api({
  endpoint_public_key: "PUB-KEY",
  endpoint_private_key: "PRIV-KEY",
});

Validate that the Api works, and credentials are correct

You can validate that the Api works, and credentials are correct by calling the authenticate method.

iocaptcha.authenticate().then((res) => {
  console.log("authenticated iocaptcha?", res);
  if (!res)
    throw new Error("Failed to authenticate iocaptcha!");
});

Verifying tokens

You can verify user-submitted tokens by calling the validate method.

iocaptcha.validate(token).then((result) => {
    console.log("result:", result);
  }).catch((err) => {
    console.log("error:", err.response.data.error);
  });

Validation result

The validate method returns a ValidationResult object, which contains the following fields:

let result = {
  pass: true,
  error: null,
  flags: ["UnavailableEnterpriseOnlyFeature"],
  score: 1.00,
  ip_match: true,
  ua_match: true
}

With this object, the field "pass" determines whether this user is valid or not, as determined by the endpoint's score threshold.

Example

This example is a simple express.js app, which validates user-submitted tokens.

import express from 'express';
import { Api } from '@iocaptcha/server';

const app = express();

const iocaptcha = new Api({
  endpoint_public_key: "AAAA",
  endpoint_private_key: "BBBB",
});

iocaptcha.authenticate().then((res) => {
  console.log("authenticated iocaptcha?", res);
});

app.use(express.json());

app.post('/login', async (req, res) => {
  let req_json = req.body;

  let token = req_json.token;
  let username = req_json.username;
  let password = req_json.password;

  console.log("verifying token:", token);

  let result = await iocaptcha.validate(token);
  if (result.pass) {
    let auth_cookie = ..login(username, password);
    if (auth_cookie) {
      res.json({
        auth_cookie
      });
    } else {
      res.json({
        "error": "Invalid username or password!"
      });
    }
  } else {
    res.json({
      "error": "Bots are not allowed on this website!"
    })
  };

});

app.listen(3000, () => {
  console.log(`Server started on port ${port}`);
});

Verifying user-submitted tokens, and their IP adress and User-Agent

You can send the user's IP address and User-Agent to the validate() function for extra verification. This is recommended, and will lower the score shall it find a mismatch, and also return the ip_match and ua_match flags as specified above.

let result = await iocaptcha.validate({
  token: ..token,
  user_ip: ..ip,
  user_useragent: ..useragent
})

Skipping invalidation

Invalidation is a process where when you make a request to our API, or use the invalidate() function, the token is marked as used and cannot be used again. This is done to prevent replay attacks, however if you want to avoid this behaviour, such as when you want to make multiple requests with the same token, you can use the invalidation option.

This is not recommended, and should only be used when you know what you're doing.

let result = await iocaptcha.validate({
  token: ..token,
  invalidate: false
})