Overview

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

Endpoints

Environment	URL
Production	https://gql-api.tokenbot.com/graphql
Development	https://gql-api-dev.tokenbot.com/graphql

Authentication

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

1. JWT bearer token — pass the access_token from the login mutation as Authorization: Bearer <access_token>.

2. CLI signed request — the x-tb-* signed-request scheme used by the tokenbot CLI.

Public operations (register, login, forgot_password) require no auth. See Authentication for full details.

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

Making Requests

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

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

{
  "data": {
    "me": {
      "success": true,
      "data": {
        "id": "user_123",
        "email": "[e-mail]"
      }
    }
  }
}

Real-Time Subscriptions

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

Documentation

• Queries — All query operations

• Mutations — All mutation operations

• Subscriptions — Real-time event streams