Palmyn Developer Documentation

Quickstart

Get Palmyn Captcha running on your site in under 5 minutes.

<form id="my-form">
  <input type="hidden" name="palmyn_token" id="captcha-token" />

  <!-- auto-renders on any .palmyn-captcha element -->
  <div class="palmyn-captcha"
       data-sitekey="pk_live_a1b2c3d4e5f6..."
       data-callback="onPalmynVerified"></div>

  <button type="submit">Submit</button>
</form>

<!-- auto-inits all .palmyn-captcha elements on load -->
<script src="https://palmyn.com/api/widget/captcha.js" async></script>
<script>
  function onPalmynVerified(token) {
    // token travels with your form to your backend
    document.getElementById('captcha-token').value = token;
  }
</script>

$token     = $_POST['palmyn_token'] ?? '';
$secretKey = getenv('PALMYN_SECRET_KEY'); // sk_live_...

$response = file_get_contents(
    'https://palmyn.com/api/captcha.php'
    . '?q=siteverify'
    . '&secret=' . urlencode($secretKey)
    . '&token='  . urlencode($token)
);

$data = json_decode($response, true);

if (!$data['success']) {
    http_response_code(403);
    die('Verification failed: ' . implode(', ', $data['error-codes'] ?? []));
}

// $data['score'] — float 0.0–1.0 (confidence of being human)
// Continue processing the form...
echo 'Verified! Score: ' . $data['score'];

const https = require('https');

async function verifyPalmyn(token) {
  const secret = process.env.PALMYN_SECRET_KEY; // sk_live_...
  const url = `https://palmyn.com/api/captcha.php`
            + `?q=siteverify&secret=${encodeURIComponent(secret)}`
            + `&token=${encodeURIComponent(token)}`;

  const res  = await fetch(url);
  const data = await res.json();

  if (!data.success) {
    throw new Error('Palmyn verification failed: ' + (data['error-codes'] || []).join(', '));
  }
  return data; // { success, score, hostname, challenge_ts }
}

// Express route example
app.post('/submit', async (req, res) => {
  try {
    const result = await verifyPalmyn(req.body.palmyn_token);
    console.log('Score:', result.score);
    res.json({ ok: true });
  } catch (err) {
    res.status(403).json({ error: err.message });
  }
});

import os, requests

def verify_palmyn(token: str) -> dict:
    secret = os.environ["PALMYN_SECRET_KEY"]  # sk_live_...
    r = requests.get(
        "https://palmyn.com/api/captcha.php",
        params={"q": "siteverify", "secret": secret, "token": token},
        timeout=5,
    )
    data = r.json()
    if not data.get("success"):
        codes = ", ".join(data.get("error-codes", []))
        raise ValueError(f"Palmyn verification failed: {codes}")
    return data  # { "success": True, "score": 0.95, ... }

# Flask example
from flask import request, abort

@app.route("/submit", methods=["POST"])
def submit():
    result = verify_palmyn(request.form.get("palmyn_token", ""))
    print("Score:", result["score"])
    return {"ok": True}

Register a Site

Every domain that embeds the Palmyn widget needs a registered key pair. Each registered site gets:

Tiers

Tell us which tier you need in your registration email.

Captcha — How it works

Install the Widget

There are two widgets you can use. Both call the same backend and return the same kind of token — pick whichever fits your stack.

Option A — Drop-in widget recommended

A declarative, reCAPTCHA-style checkbox. Add the captcha.js script once and a container with data-* attributes — it auto-renders and runs behavior scoring invisibly. No JavaScript wiring required.

<form id="my-form">
  <!-- your form fields -->
  <input type="hidden" id="palmyn-token" name="palmyn_token" />

  <!-- auto-renders on any .palmyn-captcha element -->
  <div class="palmyn-captcha"
       data-sitekey="pk_live_..."
       data-callback="onPalmynVerified"
       data-theme="light"></div>

  <button type="submit">Submit</button>
</form>

<script src="https://palmyn.com/api/widget/captcha.js" async></script>
<script>
  function onPalmynVerified(token) {
    document.getElementById('palmyn-token').value = token;
  }
</script>

If you can't serve the widget from palmyn.com/api, point it at your backend with data-api on the div, or set window.__PALMYN_API_BASE__ before the script loads. You can also skip data-callback and listen for the palmyn:verified DOM event instead.

Option B — Programmatic widget

For SPAs, custom buttons, or silent auth, use the programmatic palmyn-auth.js widget. You control where it renders and get onSuccess / onError callbacks.

<form id="my-form">
  <input type="hidden" id="palmyn-token" name="palmyn_token" />
  <div id="palmyn-captcha"></div>
  <button type="submit" id="submit-btn" disabled>Submit</button>
</form>

<script src="https://palmyn.com/api/widget/palmyn-auth.js"></script>
<script>
  new PalmynAuth({
    siteKey:   'pk_live_...',
    container: '#palmyn-captcha',
    label:     'Verificar & Continuar',   // optional: customize button text

    onSuccess: function(token) {
      document.getElementById('palmyn-token').value = token;
      document.getElementById('submit-btn').disabled = false;
    },

    onError: function(reason) {
      // reason: 'blocked' | 'expired' | 'failed' | 'error'
      alert('Verification failed. Please try again.');
    },
  });
</script>

Verify the Token

After the widget returns a token (via the callback or onSuccess), your frontend sends it to your backend. Your backend calls siteverify with your secret_key.

Request

GET https://palmyn.com/api/captcha.php
  ?q=siteverify
  &secret=sk_live_...
  &token=eyJhb...

Response

{
  "success":      true,
  "score":        0.97,
  "action":       "captcha",
  "hostname":     "miapp.com",
  "challenge_ts": "2026-05-26T14:32:10+00:00"
}

{
  "success":     false,
  "error-codes": ["invalid-input-response"]
}

Server-side verification

function palmyn_verify(string $token): array {
    $url = 'https://palmyn.com/api/captcha.php'
         . '?q=siteverify'
         . '&secret=' . urlencode(getenv('PALMYN_SECRET_KEY'))
         . '&token='  . urlencode($token);

    $ctx  = stream_context_create(['http' => ['timeout' => 5]]);
    $body = file_get_contents($url, false, $ctx);
    $data = json_decode($body, true);

    if (!($data['success'] ?? false)) {
        throw new RuntimeException('Palmyn: ' . implode(', ', $data['error-codes'] ?? ['unknown']));
    }

    return $data;
}

// Usage
try {
    $result = palmyn_verify($_POST['palmyn_token'] ?? '');
    // $result['score'] — 0.0 to 1.0
    // Process form...
} catch (RuntimeException $e) {
    http_response_code(403);
    exit($e->getMessage());
}

async function palmynVerify(token) {
  const url = new URL('https://palmyn.com/api/captcha.php');
  url.searchParams.set('q',      'siteverify');
  url.searchParams.set('secret', process.env.PALMYN_SECRET_KEY);
  url.searchParams.set('token',  token);

  const res  = await fetch(url.toString());
  const data = await res.json();

  if (!data.success) {
    throw new Error('Palmyn: ' + (data['error-codes'] || []).join(', '));
  }
  return data;
}

// Middleware example
async function requirePalmyn(req, res, next) {
  try {
    req.palmyn = await palmynVerify(req.body.palmyn_token || '');
    next();
  } catch (err) {
    res.status(403).json({ error: err.message });
  }
}

app.post('/submit', requirePalmyn, (req, res) => {
  console.log('Score:', req.palmyn.score);
  res.json({ ok: true });
});

import os
import requests
from functools import wraps
from flask import request, abort, g

PALMYN_API = "https://palmyn.com/api/captcha.php"

def palmyn_verify(token: str) -> dict:
    r = requests.get(
        PALMYN_API,
        params={
            "q":      "siteverify",
            "secret": os.environ["PALMYN_SECRET_KEY"],
            "token":  token,
        },
        timeout=5,
    )
    data = r.json()
    if not data.get("success"):
        codes = ", ".join(data.get("error-codes", ["unknown"]))
        raise ValueError(f"Palmyn: {codes}")
    return data

# Decorator for Flask routes
def require_palmyn(f):
    @wraps(f)
    def wrapper(*args, **kwargs):
        token = request.form.get("palmyn_token") or request.json.get("palmyn_token", "")
        g.palmyn = palmyn_verify(token)
        return f(*args, **kwargs)
    return wrapper

@app.route("/submit", methods=["POST"])
@require_palmyn
def submit():
    print("Score:", g.palmyn["score"])
    return {"ok": True}

Silent Auth

If a user has already completed a palm scan in your site recently (within 24 h), you can skip the QR challenge entirely by passing their Palmyn session token. The user is verified instantly.

How to enable

While we're in development phase, ping us at admin@palmyn.com and we'll flip allow_silent_auth: 1 on your registered site. Once self-service registration is open, you'll be able to toggle it yourself.

How to use it

When you initialize the widget, pass requireFresh: false and the Palmyn session token you stored after a previous successful verification.

// The palmyn_session was stored after a previous login
const palmynSession = localStorage.getItem('palmyn_session');

new PalmynAuth({
  siteKey:       'pk_live_...',
  container:     '#palmyn-captcha',
  requireFresh:  false,           // allow silent auth
  palmynSession: palmynSession,   // optional — omit if none
  onSuccess: function(token) { /* verify on server */ },
});

Widget Configuration

Drop-in widget — captcha.js

Configure the declarative widget with data-* attributes on the .palmyn-captcha container.

Programmatic widget — palmyn-auth.js

Pass these options to new PalmynAuth({ ... }).

Login with Palmyn — How it works

Login with Palmyn adds identity to the captcha flow. When a user passes verification, your backend receives not just a score — but a verified identity: a stable human_id, their email, and their verification level.

Add the Login Button

The setup is identical to the captcha widget. Use a different label to make the intent clear:

<div id="palmyn-login"></div>

<script src="https://palmyn.com/api/widget/palmyn-auth.js"></script>
<script>
  new PalmynAuth({
    siteKey:   'pk_live_...',
    container: '#palmyn-login',
    label:     'Continuar con Palmyn',  // or your preferred label

    onSuccess: async function(token) {
      // Send to your backend
      const res = await fetch('/auth/palmyn/callback', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ token }),
      });

      const { sessionCookie, redirect } = await res.json();
      window.location.href = redirect || '/dashboard';
    },

    onError: function(reason) {
      document.getElementById('login-error').textContent =
        reason === 'blocked'
          ? 'Verification failed. Are you human? 🤔'
          : 'Something went wrong. Please try again.';
    },
  });
</script>

Verify & Get User Identity

The siteverify response for Login with Palmyn includes the user's identity fields in addition to the score.

{
  "success":        true,
  "human_id":       "hid_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "email":          "usuario@ejemplo.com",
  "verified_level": 2,
  "score":          0.97,
  "action":         "palm_challenge",
  "hostname":       "miapp.com",
  "challenge_ts":   "2026-05-26T14:32:10+00:00"
}

Backend handler

function palmyn_login(string $token): array {
    $url = 'https://palmyn.com/api/captcha.php'
         . '?q=siteverify'
         . '&secret=' . urlencode(getenv('PALMYN_SECRET_KEY'))
         . '&token='  . urlencode($token);

    $data = json_decode(file_get_contents($url), true);

    if (!($data['success'] ?? false)) {
        throw new RuntimeException('Verification failed');
    }

    $humanId       = $data['human_id'];        // "hid_..."
    $email         = $data['email'];            // "user@example.com"
    $verifiedLevel = (int)$data['verified_level']; // 0 | 1 | 2

    // Only allow users with biometric verification
    if ($verifiedLevel < 2) {
        throw new RuntimeException('Biometric verification required');
    }

    // Create or find user in YOUR database
    $user = DB::firstOrCreate(
        ['palmyn_id' => $humanId],
        ['email' => $email, 'name' => explode('@', $email)[0]]
    );

    return $user; // set your session cookie etc.
}

// Route handler
try {
    $user = palmyn_login($_POST['token'] ?? '');
    $_SESSION['user_id'] = $user['id'];
    header('Location: /dashboard');
} catch (RuntimeException $e) {
    http_response_code(403);
    echo json_encode(['error' => $e->getMessage()]);
}

// routes/auth.js
app.post('/auth/palmyn/callback', async (req, res) => {
  try {
    const url = new URL('https://palmyn.com/api/captcha.php');
    url.searchParams.set('q',      'siteverify');
    url.searchParams.set('secret', process.env.PALMYN_SECRET_KEY);
    url.searchParams.set('token',  req.body.token || '');

    const data = await fetch(url.toString()).then(r => r.json());

    if (!data.success) throw new Error('Verification failed');

    const { human_id, email, verified_level } = data;

    // Only allow biometric-verified users
    if (verified_level < 2) {
      return res.status(403).json({ error: 'Biometric verification required' });
    }

    // Upsert user in your DB
    const user = await prisma.user.upsert({
      where:  { palmynId: human_id },
      create: { palmynId: human_id, email },
      update: {},
    });

    // Set session
    req.session.userId = user.id;
    res.json({ redirect: '/dashboard' });

  } catch (err) {
    res.status(403).json({ error: err.message });
  }
});

# views/auth.py
import os, requests
from flask import request, session, redirect, abort

@app.route("/auth/palmyn/callback", methods=["POST"])
def palmyn_callback():
    token = (request.json or {}).get("token", "")

    r = requests.get(
        "https://palmyn.com/api/captcha.php",
        params={
            "q":      "siteverify",
            "secret": os.environ["PALMYN_SECRET_KEY"],
            "token":  token,
        },
        timeout=5,
    )
    data = r.json()

    if not data.get("success"):
        abort(403, "Verification failed")

    human_id       = data["human_id"]         # "hid_..."
    email          = data["email"]             # "user@example.com"
    verified_level = int(data["verified_level"])  # 0 | 1 | 2

    if verified_level < 2:
        abort(403, "Biometric verification required")

    # Upsert user in your DB
    user = User.query.filter_by(palmyn_id=human_id).first()
    if not user:
        user = User(palmyn_id=human_id, email=email)
        db.session.add(user)
        db.session.commit()

    session["user_id"] = user.id
    return {"redirect": "/dashboard"}

Verification Levels

Each user has a verified_level that reflects how far they've completed the Palmyn identity process.

Mobile Deep Link

When the Palmyn widget detects a mobile browser, it automatically replaces the QR code with an "Open Palmyn App" button that deep links directly to the challenge.

If your site is registered with a redirect_uri, the Palmyn app will automatically redirect to it after the scan:

https://miapp.com/auth/palmyn/callback?palmyn_session=TOKEN_HERE

API Reference — captcha.php

Base URL: https://palmyn.com/api/captcha.php

POST verify public

Called by the widget when a user interacts with the button. Returns an action decision.

POST challenge_status public

Polled by the widget to check if the user completed the QR challenge.

GET siteverify server-to-server

Validates a token returned by the widget. Call from your backend only.

POST challenge_complete mobile app

Called by the Palmyn app after a successful palm scan. Not for third-party use.

POST get_site_info public

Returns the domain and tier for a site_key. Used by the app to display the site name before scanning.

POST register_site admin

Registers a new domain. Requires the admin secret.

API Reference — identity.php

Base URL: https://palmyn.com/api/identity.php
These endpoints are for users of the Palmyn mobile app (not for third-party site integrators).

POST check_auth_session public

Validates a Palmyn session token. Useful for backends that want to check session validity directly.

{
  "code": 200,
  "result": {
    "valid":          true,
    "human_id":       "hid_a1b2c3...",
    "email":          "user@example.com",
    "verified_level": 2,
    "expires_at":     1748397000
  }
}

Error Codes

HTTP status codes

Liveness Detection

Every palm scan in the Palmyn app runs a 4-layer liveness system inside the on-device WebView. Each check runs independently — passing requires all four.

A combined weighted score ≥ 0.60 is required — AND the correct gesture — AND a valid distance range — for 20 consecutive frames (~0.8 s each).

Challenge-response layers (app)

Privacy & Data

What we store

human_id portability

The human_id is global — the same user gets the same human_id on every site that integrates Palmyn. This means a user can be recognized across your services without re-scanning. Sites cannot reverse a human_id back to a real identity.

CORS Policy

Palmyn uses a strict, per-endpoint CORS policy. No blanket Access-Control-Allow-Origin: * is ever returned.