Documentation

Everything you need to integrate Antara into your application.

Quick Start

Get Antara running in your app in under 10 minutes.

  1. Register your app in the Antara developer dashboard
  2. Install the SDK: npm install @antara/sdk
  3. Add the OAuth login button
  4. Handle the callback to receive the user slug

OAuth 2.0 + PKCE

Antara uses the Authorization Code flow with PKCE (S256). No client secret required.

GET /oauth/authorize
  ?client_id=YOUR_APP_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &code_challenge=...
  &code_challenge_method=S256
  &state=RANDOM_STATE

After user approval, exchange the code:

POST /oauth/token
{
  "grant_type": "authorization_code",
  "code": "AUTH_CODE",
  "redirect_uri": "https://yourapp.com/callback",
  "client_id": "YOUR_APP_ID",
  "code_verifier": "ORIGINAL_VERIFIER"
}

API Authentication

API keys must be exchanged for short-lived tokens before use:

POST /auth/token/exchange
{  "apiKey": "antara_live_xxx..."  }

→ {  "accessToken": "aat_...", "expiresIn": 300  }

Use the access token as a Bearer token for all subsequent API calls.

Scopes are enforced per app token: identity.read, messages.send, and profile.basic.

Identity Lookup

Look up a user's unique slug by their Antara user ID:

POST /app/v1/identity/lookup
Authorization: Bearer aat_...
{  "userId": "user-uuid"  }

Messaging

Send messages to users via their slug. An Idempotency-Key header is required. 

POST /app/v1/messages
Authorization: Bearer aat_...
Idempotency-Key: unique-key
{
  "slug": "xK9mNp...",
  "body": "Your order #1234 shipped!"
}

Webhooks

Register webhook URLs to receive real-time event notifications. Payloads are signed with HMAC-SHA256.

Events: identity.approved, message.delivered, permission.changed

POST /app/v1/webhooks
{
  "url": "https://yourapp.com/webhook",
  "events": ["identity.approved", "message.delivered"]
}

SDK

Client-side (browser):

import { AntaraClient } from '@antara/sdk';
const antara = new AntaraClient({ appId: 'YOUR_APP_ID' });
antara.login(); // redirects to Antara

Server-side (Node.js):

import { AntaraServer } from '@antara/sdk/server';
const antara = new AntaraServer({ apiKey: 'antara_live_...' });
await antara.connect();
await antara.send({ slug: '...', message: 'Hello!' });

Trust & Moderation

Antara exposes explainable trust and moderation metadata so users and developers can make informed decisions.

  • Trust levels: private, unverified, verified
  • Trust score breakdown: domain bonus, age factor, report penalties, behavior penalties
  • Moderation states: clean, warn, restrict, disabled

Read the full model at /trust-model.