Documentation

Everything you need to integrate Antara into your application.

Quick Start

Get Antara running in your app in under 10 minutes.

Register your app in the Antara developer dashboard
Install the SDK: npm install @antara/sdk
Add the OAuth login button
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

In a normal browser, GET /oauth/authorize redirects to the Antara site consent screen at /oauth/consent (same query string). Programmatic clients can call the API with Accept: application/json to receive consent metadata directly.

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"
}

Antara ID & per-app isolation

Your Antara account is separate from what apps see. Each approved integration receives an Antara ID: a random per-app slug (and optional display alias you control). That value is all the app needs to recognize you as a unique user for its own product logic.

No shared identifier across apps — different apps get different slugs, so they cannot correlate accounts with each other through Antara.
Email and phone stay with Antara — they are not exposed to apps as part of the standard OAuth or API-key flows described here.

User session (browser)

After email verification, the client posts the signed code to POST /auth/exchange-code. The response wraps tokens and profile in data and tracing in meta:

{
  "data": {
    "accessToken": "uat_...",
    "tokenType": "Bearer",
    "expiresAt": 1710000000,
    "expiresIn": 600,
    "sessionType": "user",
    "audience": "useantara",
    "scopes": ["ai.chat", "identity.read", "messages.send", "profile.basic"],
    "user": {
      "id": "…",
      "primarySlug": "your-handle",
      "displayName": "Your name",
      "trustLevel": "L1",
      "verified": true
    }
  },
  "meta": { "requestId": "…", "issuedAt": 1710000000 }
}

Errors return error: { "code", "message" } plus requestId (and optional retryAfter for rate limits).

Machine clients may use POST /auth/client-token with client_id (app UUID) and client_secret (full API key); optional scopes narrows the grant. POST /auth/introspect with { "token": "…" } returns active, scopes, and session context for supported token types.

API Authentication

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

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

→ { "data", "meta" } envelope: sessionType "app", audience = app id, scopes, app { appId, name }

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

Scopes are enforced per app token. Common values: identity.read (resolve a stable Antara ID), messages.send (outbound messaging), and ai.chat (gated AI). Legacy alias tokens identify / message are still accepted where mapped.

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

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

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

API-first messaging & capability tokens

Messages are delivered over HTTPS APIs only. A logical address <slug>@useantara.com identifies the recipient in POST /app/v1/messages when using a capability bearer (Authorization: Bearer cap_…). Tokens are scoped (for example messages.send), may expire, and can bind to origins or email addresses. Antara does not operate user mailboxes or ingest inbound SMTP for these addresses.

Preview a connect invite: POST /public/v1/cap-tokens/preview with { "token": "cap_…", "slug": "your-slug" }.

SDK

Client-side (browser) — package @antara/web-sdk:

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

Server-side — package @antara/server-sdk:

import { AntaraServer } from '@antara/server-sdk';
const antara = new AntaraServer({ apiKey: 'antara_live_...' });
await antara.connect();
await antara.send({ slug: '...', message: 'Hello!' });
// Optional: await antara.aiChat({ messages: [{ role: 'user', content: 'hi' }] });

Scopes on new keys include identity.read, messages.send, and ai.chat (for the gated /app/v1/ai/chat endpoint).

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.

Documentation i