API overview

{
  "data": {
    "data": {
      "anchor_grant_token": "bss_4b1e…",
      "anchor_grant_expires_at": "2026-09-21T18:36:45.000Z",
      "anchor_grant_expires_in_seconds": 300,
      "session_token": "bss_4b1e…",
      "expires_at": "2026-09-21T18:36:45.000Z",
      "expires_in_seconds": 300,
      "organization": { "id": "org_…", "environment": "production" }
    }
  }
}

{
  "data": {
    "error": {
      "message": "Invalid API token: Invalid or inactive API token",
      "statusCode": 401
    }
  }
}

curl -s https://api.botshield.ai/operations/sdk/create-session \
  -H "Authorization: Bearer $BOTSHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"partner_user_id": "user_8842"}' \
  | jq 'if .data.error then {failed: .data.error} else {grant: .data.data.anchor_grant_token} end'

type Envelope<T> = {
  data: { data?: T; error?: { message: string; statusCode: number; code?: string } };
};

type Session = { anchor_grant_token: string; anchor_grant_expires_in_seconds: number };

const response = await fetch("https://api.botshield.ai/operations/sdk/create-session", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOTSHIELD_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ partner_user_id: "user_8842" }),
});

// response.ok is true even when the operation failed. Check data.error.
const body = (await response.json()) as Envelope<Session>;

if (body.data.error) {
  throw new Error(`${body.data.error.statusCode}: ${body.data.error.message}`);
}

const grantToken = body.data.data!.anchor_grant_token;

import { BotShield } from "botshield-sdk";

const botshield = new BotShield({
  serverURL: "https://api.botshield.ai/operations",
});

const result = await botshield.census.createSession(
  { apiKeyAuth: `Bearer ${process.env.BOTSHIELD_API_KEY}` }, // include the "Bearer " prefix
  { partnerUserId: "user_8842" },
);

// The SDK does not unwrap the envelope. Field names are camelCase.
if (result.data.error) {
  throw new Error(`${result.data.error.statusCode}: ${result.data.error.message}`);
}

const grantToken = result.data.data!.anchorGrantToken;