Quickstart

This walkthrough takes you from an empty account to a working integration in three steps: an API key, a first call to the Reward API, and a webhook endpoint that receives Tanitar events.

You need:

• Access to the Tanitar dashboard as an administrator of your organization.
• The base URLs Tanitar provides for your environment. This page uses REWARD_API_URL; see authentication for the full list.
• An HTTPS URL you control, for the webhook step.

1. Create an API keyCopy Anchor Link

1. Sign in to the dashboard and open API keys.
2. Select Create API key.
3. Enter a Key name that says what the key is for, for example rewards-backend.
4. Select the scopes the key needs. For this quickstart, select rewards:read and rewards:mutate. The dashboard only offers scopes your plan allows.
5. Optionally set an Expiry.
6. Submit. The dialog titled Save this key now shows the full key once. Copy it and store it in your secret manager: Tanitar stores only a digest and cannot show it again.

Export the key and the base URL in your shell:

export TANITAR_API_KEY="defendr_key_…"      # the value you just copied
export REWARD_API_URL="https://…"           # provided by Tanitar for your environment

2. Make your first callCopy Anchor Link

List the currencies registered on your account with GET /v1/currencies:

curl "$REWARD_API_URL/v1/currencies" \
  -H "Authorization: Bearer $TANITAR_API_KEY"

A new account has none yet:

{
  "revision": 0,
  "entries": []
}

Now create one with POST /v1/currencies. This is a mutation, so it needs an Idempotency-Key header: a unique value per logical operation (see idempotency):

curl -X POST "$REWARD_API_URL/v1/currencies" \
  -H "Authorization: Bearer $TANITAR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"currencyKey": "gems", "displayName": "Gems", "scope": "platform", "precision": 0}'

The API answers 201 with the new registry entry. It starts as a draft (abridged):

{
  "currencyKey": "gems",
  "displayName": "Gems",
  "scope": "platform",
  "precision": 0,
  "status": "draft",
  "revision": 1,
  "createdAt": "2026-09-30T09:12:44.103Z",
  "updatedAt": "2026-09-30T09:12:44.103Z"
}

A draft currency cannot be used yet. Publish it with POST /v1/currencies/:currencyKey/publish when you are ready; the currencies guide covers the lifecycle.

When something goes wrongCopy Anchor Link

Every error uses the same envelope. For example, a key without rewards:mutate gets a 403:

{
  "success": false,
  "statusCode": 403,
  "responseType": "FORBIDDEN",
  "errorCode": "ACCESS_SCOPE_DENIED",
  "message": "Forbidden",
  "data": null,
  "requestId": "6f1c2a9e-3a55-4c1e-9d2b-8a0f4e7c1b20",
  "timestamp": "2026-09-30T09:13:02.551Z"
}

Branch on errorCode, never on message. Keep the requestId when you contact Tanitar support. The errors page lists the codes shared by every API.

3. Register a webhook endpointCopy Anchor Link

Webhooks push events such as a settled grant, completed mission or finished tournament to your back end. You manage endpoints in the dashboard.

1. Open Webhooks in the dashboard and choose Register an endpoint.
2. Enter your HTTPS endpoint URL and an optional description.
3. The dashboard shows the endpoint's signing secret once. Store it, confirm I have stored this signing secret, and continue.
4. Choose the Event types the endpoint should receive. The event catalog describes each one.
5. Send a test delivery. Your endpoint must answer it successfully before it can be enabled.
6. Enable the endpoint. From now on, every subscribed event is delivered to it and recorded in the Deliveries log.

Before trusting a delivery, verify its signature with the secret from step 3. See verifying signatures.

Next stepsCopy Anchor Link