Skip to content
TokenBotTokenBotTokenBot

GraphQL API Overview

The GraphQL API provides full access to the TokenBot platform, including authentication, user management, and admin operations.

Endpoints

Section titled “Endpoints”
EnvironmentURL
Productionhttps://gql-api.tokenbot.com/graphql
Developmenthttps://gql-api-dev.tokenbot.com/graphql

Authentication

Section titled “Authentication”

The GraphQL API is an Express server (deployed on ECS Fargate) and accepts two auth methods:

  1. CLI signed request (canonical) — the x-tb-* signed-request scheme used by the tokenbot CLI and recommended for new integrations.
  2. JWT bearer token (legacy) — an Authorization: Bearer <access_token> token, retained for back-compat.

The password/OAuth/passkey/2FA login mutations are dashboard-era and deprecated — they still resolve but aren’t documented as usable endpoints. See Authentication for the canonical flow and the full deprecated list.

AWS AppSync + Cognito was retired (PR #148); there is no longer Cognito or x-api-key auth.

Making Requests

Section titled “Making Requests”
Terminal window
curl -X POST https://gql-api.tokenbot.com/graphql \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { me { success data { id email } } }"
  }'

Response Format

Section titled “Response Format”

Most operations return a typed response with success, data, and optional error:

{
  "data": {
    "me": {
      "success": true,
      "data": {
        "id": "user_123",
        "email": "user@example.com"
      }
    }
  }
}

Real-Time Subscriptions

Section titled “Real-Time Subscriptions”

TokenBot supports GraphQL subscriptions for live updates. See Subscriptions for details and the available channels.

Documentation

Section titled “Documentation”