Developers

Access

Every call carries a token in the Authorization header. You create your own token in the settings — this requires a Club plan. Companies receive group-wide tokens through support.

Authorization: Bearer ity_…

A token is bound either to one account or to one group. A group token names the acting member via user_email on every call and rejects non-members.

Scopes

• profile:readRead profile and record
• challenges:readRead challenges
• challenges:writeCreate and answer challenges
• events:readRead the event feed
• group:readRead group and members
• group:manageManage members
• webhooks:manageManage webhooks
• questions:readRead the daily question
• questions:voteVote on the daily question

Create your first challenge

curl -X POST https://intayo.com/api/v1/challenges \
  -H "Authorization: Bearer ity_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mein-lauf-001" \
  -d '{
    "claim": "Ich laufe den Halbmarathon unter zwei Stunden",
    "opponent_email": "[email protected]",
    "stake": "coffee",
    "due_days": 30
  }'

The Idempotency-Key header ensures that retrying after a network error does not create a second challenge.

Endpoints

Lists return next_cursor — pass that value as cursor on the next call. limit goes up to 100.

Webhooks

Instead of polling, let INTAYO notify you. Every delivery carries a signature in the X-ITY-Signature header. Verify it before using the payload — otherwise anyone can feed your endpoint.

import { createHmac, timingSafeEqual } from 'crypto';

export function verify(secret, header, rawBody) {
  const parts = Object.fromEntries(
    header.split(',').map((p) => p.trim().split('='))
  );
  const alter = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!(alter < 300)) return false;

  const erwartet = createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  return parts.v1.length === erwartet.length &&
    timingSafeEqual(Buffer.from(parts.v1), Buffer.from(erwartet));
}

Failed deliveries are retried five times with growing intervals, after which the subscription is switched off.

Limits and errors

120 read and 30 write calls per minute and token. The X-RateLimit-Remaining and X-Quota-Remaining headers tell you what is left.

Every response carries a request_id, also in the X-Request-Id header. Please include it when contacting support.

Respect for the other side

A challenge always involves two people. That is why the API only exposes the other person’s first name — never a surname, never an email address. When you move data into other services, you also move data about someone who does not know about it. Handle it sparingly.