Getting Started with Yaan

Get invisible bot protection running on your site in just a few minutes. No CAPTCHAs, no user friction, just seamless protection.

Step 1: Create an Account

Sign up at your Yaan dashboard
Verify your email
Log in to access your dashboard

Step 2: Add Your Website

Navigate to Dashboard → Websites
Click "Add Website"
Enter your domain (e.g., example.com)
Click "Create"
Copy your Sitekey and Client Secret

Keep your Client Secret private! Never expose it in client-side code or public repositories.

Step 3: Install the Script

Add the Yaan script to your website's HTML, preferably in the <head> section:

<script
  src="https://cdn.yaan.com/apricot.js"
  data-sitekey="YOUR_SITEKEY_HERE"
  async
></script>

Step 4: Protect Your Forms

Add token verification to your form submissions. The Yaan script exposes a global window.Apricot.requestToken() method that returns a verification token.

Example: Contact Form

<form id="contact-form">
  <input type="text" name="name" placeholder="Your Name" required />
  <input type="email" name="email" placeholder="Your Email" required />
  <textarea name="message" placeholder="Your Message" required></textarea>
  <button type="submit">Send Message</button>
</form>

<script>
  document
    .getElementById("contact-form")
    .addEventListener("submit", async (e) => {
      e.preventDefault();

      try {
        // Request Yaan verification token
        const token = await window.Apricot.requestToken();

        // Prepare form data
        const formData = new FormData(e.target);
        formData.append("yaan_token", token);

        // Submit to your backend
        const response = await fetch("/api/contact", {
          method: "POST",
          body: formData,
        });

        if (response.ok) {
          alert("Message sent successfully!");
          e.target.reset();
        } else {
          alert("Failed to send message. Please try again.");
        }
      } catch (error) {
        console.error("Yaan error:", error);
        alert("Verification failed. Please try again.");
      }
    });
</script>

Step 5: Verify Tokens Server-Side

Critical: Always verify tokens on your backend. Never trust client-side verification alone.

const express = require("express");
const app = express();

async function verifyYaanToken(token, clientSecret, ipAddress, email) {
  const response = await fetch("https://api.yaan.com/sus", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      diamond: token,
      clientsecret: clientSecret,
      ip_addr: ipAddress,
      email_domain: email ? email.split("@")[1] : null,
    }),
  });

  const result = await response.json();
  return !result.block; // true if human, false if bot
}

app.post("/api/contact", async (req, res) => {
  const { yaan_token, name, email, message } = req.body;
  const clientSecret = process.env.YAAN_CLIENT_SECRET;
  const ipAddress = req.ip;

  // Verify with Yaan
  const isHuman = await verifyYaanToken(
    yaan_token,
    clientSecret,
    ipAddress,
    email,
  );

  if (!isHuman) {
    return res.status(403).json({ error: "Bot detected" });
  }

  // Process the contact form...
  // Save to database, send email, etc.

  res.json({ success: true });
});

from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)

def verify_yaan_token(token, client_secret, ip_address, email=None):
    email_domain = email.split('@')[1] if email else None

    response = requests.post('https://api.yaan.com/sus', json={
        'diamond': token,
        'clientsecret': client_secret,
        'ip_addr': ip_address,
        'email_domain': email_domain
    })

    result = response.json()
    return not result['block']  # True if human

@app.route('/api/contact', methods=['POST'])
def contact():
    data = request.json
    token = data.get('yaan_token')
    email = data.get('email')

    client_secret = os.getenv('YAAN_CLIENT_SECRET')
    ip_address = request.remote_addr

    # Verify with Yaan
    is_human = verify_yaan_token(token, client_secret, ip_address, email)

    if not is_human:
        return jsonify({'error': 'Bot detected'}), 403

    # Process the contact form...
    # Save to database, send email, etc.

    return jsonify({'success': True})

<?php
function verifyYaanToken($token, $clientSecret, $ipAddress, $email = null) {
    $emailDomain = $email ? explode('@', $email)[1] : null;

    $data = [
        'diamond' => $token,
        'clientsecret' => $clientSecret,
        'ip_addr' => $ipAddress,
        'email_domain' => $emailDomain
    ];

    $options = [
        'http' => [
            'method' => 'POST',
            'header' => 'Content-Type: application/json',
            'content' => json_encode($data)
        ]
    ];

    $context = stream_context_create($options);
    $response = file_get_contents('https://api.yaan.com/sus', false, $context);
    $result = json_decode($response, true);

    return !$result['block']; // true if human
}

// In your contact form handler
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $token = $_POST['yaan_token'];
    $email = $_POST['email'];
    $clientSecret = $_ENV['YAAN_CLIENT_SECRET'];
    $ipAddress = $_SERVER['REMOTE_ADDR'];

    // Verify with Yaan
    $isHuman = verifyYaanToken($token, $clientSecret, $ipAddress, $email);

    if (!$isHuman) {
        http_response_code(403);
        echo json_encode(['error' => 'Bot detected']);
        exit;
    }

    // Process the contact form...
    // Save to database, send email, etc.

    echo json_encode(['success' => true]);
}
?>

Configuration Options

Script Tag Attributes

Attribute	Required	Description
`data-sitekey`	Yes	Your unique sitekey from the dashboard

Environment Variables (Backend)

Set these on your application server:

YAAN_CLIENT_SECRET=your_client_secret_here

Next Steps

API Reference - Complete API documentation
Framework Integration - React, Vue, Next.js guides
Security Best Practices - Maximize protection
Dashboard - View analytics and manage websites

Troubleshooting

Token not being generated?

Check browser console for errors
Ensure the script loaded successfully (check Network tab)
Verify window.Apricot is defined before calling requestToken()
Confirm your sitekey is correct

Always getting blocked?

Verify client secret matches your dashboard
Ensure IP address is being passed correctly
Check that you're calling the /sus endpoint (not /telemetry)
Review analytics dashboard for bot detection details

Script not loading?

Check for CORS errors in console
Verify the script URL is accessible
Ensure no ad blockers are interfering
Try loading the script without async attribute for debugging

Need Help?

Check our troubleshooting guide
Join our community forum
Contact support at support@yaan.com