Skip to content

Developers · API v1

Award TISH from your platform.

Your people earn for work you checked. They keep one balance across every platform that uses TISH, and you never handle money, points tables or fraud rules of your own.

Get started in 5 minutes

  1. Get test keys. Sign in to insiderOne and register your platform in the developer console. A test key comes with it at once, and a first rule, lesson_completed, so your first earn settles. Put TISH_KEY_ID and TISH_KEY_SECRET in your server's environment. Test mode never creates TISH.
  2. Drop in the kit. One script tag on your pages, for the TISH mark, a balance and the Connect TISH button. It never sees a key.
    HTML
    <script src="https://tishlabs.insiderone.in/kit/v1/tish.js" defer data-badge="bottom-right"></script>
  3. Sign and send POST /v1/earn from your server when one of your people does something you checked.
    curl + openssl
    t=$(date +%s); path=/v1/earn
    body='{"user":"usr_8812","action":"lesson_completed","idempotency_key":"quiz_44:usr_8812","evidence":{"type":"quiz_score","ref":"quiz_44","value":0.9}}'
    hash=$(printf '%s' "$body" | openssl dgst -sha256 -hex | awk '{print $NF}')
    sig=$(printf '%s\n%s\n%s\n%s' "$t" POST "$path" "$hash" \
      | openssl dgst -sha256 -hmac "$TISH_KEY_SECRET" -hex | awk '{print $NF}')
    curl -s "https://api.tishlabs.insiderone.in$path" -X POST \
      -H "authorization: TISH key=$TISH_KEY_ID, t=$t, sig=$sig" \
      -H "content-type: application/json" \
      --data-raw "$body"
    Node.js 18+
    import crypto from "node:crypto";
    
    const KEY_ID = process.env.TISH_KEY_ID;        // key_test_…
    const SECRET = process.env.TISH_KEY_SECRET;    // tsk_test_…  never sent
    
    async function tish(method, path, body = "") {
      const t = Math.floor(Date.now() / 1000);
      const bodyHash = crypto.createHash("sha256").update(body).digest("hex");
      const sig = crypto.createHmac("sha256", SECRET)
        .update(`${t}\n${method}\n${path}\n${bodyHash}`).digest("hex");
      const res = await fetch("https://api.tishlabs.insiderone.in" + path, {
        method,
        headers: {
          authorization: `TISH key=${KEY_ID}, t=${t}, sig=${sig}`,
          "content-type": "application/json",
        },
        body: body || undefined,
      });
      return res.json();
    }
    
    // A learner passed a quiz you marked. Your own id for them, never an email.
    console.log(await tish("POST", "/v1/earn", JSON.stringify({
      user: "usr_8812",
      action: "lesson_completed",
      idempotency_key: "quiz_44:usr_8812",
      evidence: { type: "quiz_score", ref: "quiz_44", value: 0.9 },
    })));
    Python 3
    import hashlib, hmac, json, os, time, urllib.request
    
    KEY_ID, SECRET = os.environ["TISH_KEY_ID"], os.environ["TISH_KEY_SECRET"]
    
    def tish(method, path, body=""):
        t = int(time.time())
        body_hash = hashlib.sha256(body.encode()).hexdigest()
        msg = f"{t}\n{method}\n{path}\n{body_hash}".encode()
        sig = hmac.new(SECRET.encode(), msg, hashlib.sha256).hexdigest()
        req = urllib.request.Request("https://api.tishlabs.insiderone.in" + path, data=body.encode() or None, method=method,
            headers={"authorization": f"TISH key={KEY_ID}, t={t}, sig={sig}",
                     "content-type": "application/json"})
        return json.load(urllib.request.urlopen(req))
    
    print(tish("POST", "/v1/earn", json.dumps({
        "user": "usr_8812",
        "action": "lesson_completed",
        "idempotency_key": "quiz_44:usr_8812",
        "evidence": {"type": "quiz_score", "ref": "quiz_44", "value": 0.9},
    })))

    The answer is an earn with status: "settled" and mode: "test". Send the same request again and it answers replayed: true: nobody is paid twice.

  4. Go live. Propose your rules in the console and choose Request live access. We review your platform (below), agree your rules, and switch on a starting monthly budget. Then you make live keys in the console and swap them in.

How it works

You agree a small set of rules with us: which actions on your platform earn, how much, and how often a day. When one of your people does one of those things and you have checked it, your server calls POST /v1/earn. The ledger pays it from the community pool, inside your platform's monthly budget, and records it on the same hash-chained ledger every platform writes to.

You name people by your own id for them. Until a person connects their TISH account, what they earn is held for them under that id. When they connect, it moves to them, and from then on they see one balance for everything they have earned anywhere.

TISH has no money value and cannot be bought or cashed out, so nothing here is a payment. The integration is free.

Keys

You get two values per key, a key id and a key secret: a TISH_KEY_ID that names the key, and a TISH_KEY_SECRET that signs your requests and is never sent anywhere. We do not keep the secret either; if it is lost, we issue a new key.

Test keys (key_test_…) are yours the moment you register a platform in the developer console. They follow your rules, proposed or agreed, and their daily limits, write to a separate test ledger and never create a single TISH. Live keys (key_live_…) you make in the console once your platform is approved for live. Rotate or revoke any key there. Keep both on your server only.

Signing a request

Every request carries one header. The signature is an HMAC-SHA256, under your secret, of four lines: the Unix timestamp, the method, the path with its query string, and the SHA-256 of the body (of an empty string for a GET).

Header
Authorization: TISH key=<TISH_KEY_ID>, t=<unix seconds>, sig=<hex HMAC-SHA256>

A timestamp more than 5 minutes from ours is refused, so a captured request cannot be replayed later, and a replayed earn inside those minutes is answered as the original. An unknown key, a revoked key and a wrong signature all get the same 401. Sign the path exactly as you send it, with its query string, and the body byte for byte. Each key may make 300 requests a minute, your platform 600 across all its keys, and one address 600. The samples are in Get started.

Endpoints

All under https://api.tishlabs.insiderone.in. Answers are JSON. Errors are { error: { code, message } }.

GET/v1/pingChecks your key and signature. Answers your platform and mode.
POST/v1/earnAwards TISH for a checked action, by one of your agreed rules.
GET/v1/users/{user}/balanceWhat one of your people holds, and whether they have linked.
GET/v1/ledgerYour platform's entries, newest first. ?limit= (up to 100) and ?before= to page.
GET/v1/rulesYour rules: agreed ones, and in test mode the ones still proposed.
POST/v1/link_sessionsStarts Connect TISH for one of your people. Send them to the url it returns.
GET/v1/link_sessions/{id}Whether they connected: open, linked, declined or expired.
  • Authorization: TISH key=<TISH_KEY_ID>, t=<unix seconds>, sig=<hex HMAC-SHA256>. Every request.
  • Content-Type: application/json, on every POST.
  • Idempotency-Key: Optional on POST /v1/earn, instead of idempotency_key in the body.

Earning

POST /v1/earn takes user (your id for the person: letters, digits and _ . : @ -, never an email address), action (one of your rules), idempotency_key (or an Idempotency-Key header) and evidence: what you checked, as { type, ref, value? }.

The idempotency key makes retries safe: send the same key again, after a timeout or a crash, and you get the first answer back with replayed: true. Nobody is ever paid twice for one event. Use the id of the thing that happened, such as the quiz attempt. The same key for a different person or action is not a retry: it is declined as idempotency_key_reused and nothing is awarded.

Platforms run by insiderOne (Ricorda, HyperQuark Labs) also send email_sha256: the SHA-256 of the person's verified email, lowercased. One verified email is one TISH wallet, so their TISH lands in the same wallet everywhere. Every other platform uses Connect TISH instead, because sharing a person's address between companies needs their yes: from any other platform, email_sha256 is refused with a 400.

Response
{
  "object": "earn",
  "id": "ern_test_1042",
  "mode": "test",
  "status": "settled",          // or "declined"
  "replayed": false,            // true when this was a retry of an earn already made
  "reason": null,               // why it was declined, e.g. "daily_cap"
  "user": "usr_8812",
  "action": "lesson_completed",
  "amount": 5,
  "linked": false,              // has this person connected their TISH account?
  "balance": 15                 // what they hold (before linking: what is held for them)
}

Errors

Every error is { error: { code, message } } with one of these statuses. A declined earn is not an error: it is a 200 with a reason, below.

400invalid_requestThe body or a field is wrong. The message says which, and how to fix it.
401unauthorizedNo signature, a signature that does not match, or a key that does not exist or was revoked. All three look the same, on purpose.
401stale_timestampThe timestamp is more than five minutes from ours. Check the server's clock.
403forbiddenA restricted key tried something other than earning, or a live key of a platform that is not live started a link.
404not_foundNo such endpoint, or no such link session for your platform.
405method_not_allowedUse GET or POST.
413too_largeBodies are at most 8 KB.
429rate_limitedToo many requests this minute, for this key, your platform or your address. Retry after a short wait, with the same idempotency key.
500server_errorOur side. Retry with the same idempotency key; nobody is paid twice.
503not_openThe API is not open yet.

When an earn is declined

A declined earn is still a 200: the request was fine and the ledger said no. The answer carries a reason and a sentence you can log.

  • not_an_earning_actionThis action is not one of your platform's agreed rules.
  • daily_capThis person reached the daily limit for this action.
  • platform_budgetYour platform's monthly TISH budget is used up.
  • emission_pausedThis month's community emission is used up. Earning resumes on the 1st.
  • platform_not_liveYour platform is not live yet. Use your test keys until it is.
  • platform_pausedEarning on your platform is paused. Contact TISH Labs.
  • held_for_reviewUnusually many new people today. Further new people are held for review.
  • frozenThis person's TISH account is frozen.
  • unknown_platformThis key's platform does not exist.
  • first_partyThis platform posts through its own server, not the API.
  • idempotency_key_reusedThis idempotency key was already used for a different person or action. Nothing was awarded: use one key per event.
  • reserved_idempotency_keyIdempotency keys starting release:, reclaim: or migrate: are reserved.
  • test_daily_limitYour platform reached today's limit of 5,000 test earns. Test mode resumes tomorrow (UTC).

Connect TISH

When one of your people wants their TISH in one place, your server calls POST /v1/link_sessions with user and, optionally, a return_url on an origin you registered with us. Send the person to the url in the answer. They sign in to insiderOne, see that you will see their TISH balance and nothing else about them, and approve.

They come back to your return_url with tish_session and tish_status added. Confirm with GET /v1/link_sessions/{id} rather than trusting the address. Whatever you held for them moves into their account at that moment, and from then on what they earn with you goes straight to them.

A session works once and lasts 30 minutes. Your server makes it, so only you can say which of your users is connecting. People disconnect whenever they like from their wallet; what they earned stays theirs. TISH held for someone who never connects returns to the community pool after 12 months.

Drop-in kit

One script tag gives your site the TISH mark, a "TISH Compatible" badge, a balance pill or card, the Connect TISH button and the earn toast. They are self-contained web components: no framework, no stylesheet to load, and your CSS cannot break them. The kit only draws. It never calls the API and never sees a key: your server reads the balance and starts Connect TISH, and passes the result in.

Two rules every platform keeps

1. TISH numbers carry the TISH mark, once per group. People recognise TISH by it, and a mark on every number is noise: a card or a list shows it once, on its main number or its heading. Use <tish-amount> or <tish-balance>, and mark="false" for the numbers inside a group that already shows it.

2. Your site has a TISH page, linked from your menu. <tish-page> is the whole page: balance, wallet ID, tier, how people earn on your platform (your agreed rules, read live from TISH Labs), what TISH is, and Connect TISH for people who have not connected yet.

We check both before a platform goes live.

Install
<script src="https://tishlabs.insiderone.in/kit/v1/tish.js" defer data-badge="bottom-right"></script>
Use
<tish-mark size="24"></tish-mark>
<tish-badge></tish-badge>
<tish-balance amount="240" tier="curator"></tish-balance>
<tish-balance amount="240" tier="curator" variant="card"></tish-balance>
<tish-connect href="/account/connect-tish"></tish-connect>
<tish-amount value="25" sign="+"></tish-amount>

<!-- Your site's TISH page, e.g. at /tish, linked from your menu -->
<tish-page platform="your-platform-id" amount="240" tier="curator"
           wallet-id="TISH-7K3F-9QX2-M8PA" connect-href="/account/connect-tish"></tish-page>

<script>
  // After your server confirmed an earn (POST /v1/earn answered "settled"):
  TISH.toast({ amount: 5, label: "Saved a link" });
</script>

Going live

  1. Register. In the developer console, with your platform's name and website. Test keys come at once. Questions: tishlabs@insiderone.in.
  2. Build, and propose your rules. Your actions, amounts and daily limits, in the console. Proposed rules work in test mode straight away; then choose Request live access.
  3. Sign the TISH Platform Agreement. No money changes hands either way.
  4. Review. We run your flow in test mode, check the evidence you send, and check your TISH page and that every TISH number carries the mark.
  5. Live. Your rules agreed and a starting monthly budget switched on, raised once your platform has a record. You make your live keys in the console.

Coming next: spending with the person's approval inside your platform, signed webhooks for every settled earn, a command-line tool, and SDKs for Node, Python and PHP. Everything above works from any language today.