tellr
Download all
Docs · Getting started

Quickstart

Wire Tellr into any app — local or production — in five steps. Total time: about ten minutes. Below the URLs are the addresses your local Tellr stack is running on right now.

Your local Tellr endpoints
  • SDK scripthttp://localhost:8081/v1/c.js
  • Collectorhttp://localhost:8081
  • Check APIhttp://localhost:8080

On production these become cdn.tellr.com, collect.tellr.com, and api.tellr.com. The shape of every request is identical.

1. Sign up & grab your keys

If you haven't already, create an account. You'll land in a fresh project. Go to Install in the dashboard — it shows your project's public key, a button to create a secret API key, and copy-paste snippets pre-filled for your stack.

You need two keys:

  • Public key (pk_…) — embedded in your <script> tag. Origin-restricted, safe to commit.
  • Secret API key (tk_live_…) — used from your server. Treat like a password, store in env vars.

2. Drop the SDK into your frontend

One script tag in <head>. The SDK auto-initializes on page load, collects ~110 device signals in the background, and writes a 30-minute session cookie. About 8 KB gzipped.

html
<script
  src="http://localhost:8081/v1/c.js"
  data-key="pk_••••"
  data-collector="http://localhost:8081"
></script>

The data-collector attribute tells the SDK where to POST session payloads. On production you can omit it and the SDK defaults to https://collect.tellr.com.

3. Call /v1/check from your backend on signup

When a user submits your signup form, read the session cookie from the request and post it to /v1/check along with whatever identity fields you have.

bash
curl -X POST http://localhost:8080/v1/check \
  -H "Authorization: Bearer tk_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "session_token": "tk_sess_xxx",
    "end_user": { "email": "alice@example.com" }
  }'

4. Act on the verdict

The response includes a verdict (allow, flag, or block), a 0–100 score, the 18-digit tellr_id to store on your user record, and a human-readable explanation array.

ts
const r = await tellr.check({ session_token, end_user });

if (r.verdict === 'block') {
  return res.status(403).end();
}

await db.users.update({
  where: { id: userId },
  data: { tellr_id: r.tellr_id },
});

5. Test it from another localhost site

Save the file below as test.html on your machine, open it (open test.html or serve it from any port), then refresh once. The SDK sets a cookie and the dashboard reflects it instantly under Checks the moment your backend calls /v1/check.

html
<!doctype html>
<html>
<head>
  <meta charset="utf-8" />
  <script
    src="http://localhost:8081/v1/c.js"
    data-key="pk_••••"
    data-collector="http://localhost:8081"
  ></script>
</head>
<body>
  <h1>Tellr test</h1>
  <button id="show">Show session token</button>
  <pre id="out"></pre>
  <script>
    document.getElementById('show').addEventListener('click', async () => {
      const t = await window.__tellr.getSessionToken();
      document.getElementById('out').textContent = t;
    });
  </script>
</body>
</html>
The dashboard's Install page has a one-click verifier that loads your SDK, posts a session, and confirms both endpoints answer. Run it once before integrating.

What to read next

  • Concepts — composite IDs, verdicts, thresholds, the tellr_id format.
  • API reference — every endpoint, every error code.
  • All 267 signals — full reference with score weights.
  • SDKs — Node, Python, Ruby, Go, PHP wrappers.
  • Self-hosting — run Tellr inside your own VPC.