Tellr
Start
Download all
Docs · Getting started

Quickstart

Wire Tellr into any app in five steps that should take you about ten minutes from start to finish. Every snippet below uses the production endpoints so you can copy them straight into your code.

Production Tellr endpoints
  • SDK scripthttps://cdn.tellr.tech/v1/c.js
  • Collectorhttps://collect.tellr.tech
  • Check APIhttps://api.tellr.tech

Every Tellr customer talks to the same hosts and the shape of every request is identical no matter what stack you run.

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 plus copy paste snippets prefilled for your stack.

You need two keys:

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

2. Drop the SDK into your frontend

One script tag in <head> is all you need. The SDK auto initializes on page load, collects around 110 device signals in the background then writes a 30 minute session cookie. About 8 KB gzipped.

html
<script
  src="https://cdn.tellr.tech/v1/c.js"
  data-key="pk_••••"
  data-collector="https://collect.tellr.tech"
></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.tech.

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 https://api.tellr.tech/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 to 100 score, the 18 digit tellr_id to store on your user record plus 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 so 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="https://cdn.tellr.tech/v1/c.js"
    data-key="pk_••••"
    data-collector="https://collect.tellr.tech"
  ></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 then confirms both endpoints answer. Run it once before integrating.

What to read next

  • Concepts covers composite IDs, verdicts, thresholds plus the tellr_id format.
  • API reference walks through every endpoint along with every error code.
  • All 267 signals is the full reference with score weights.
  • SDKs covers Node, Python, Ruby, Go plus PHP wrappers.
  • Webhooks push verdicts to billing, ops or SIEM.