Authentication

TokenBot supports multiple authentication methods depending on the API you're using.

REST API Authentication

API Key (Recommended)

Send your API key via the X-API-Key header:

curl https://rest-api.tokenbot.com/v1/exchanges \
  -H "X-API-Key: tb_live_your_api_key"

JWT Bearer Token

Alternatively, use a JWT token obtained from the GraphQL login mutation:

curl https://rest-api.tokenbot.com/v1/exchanges \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

API Key Format

Environment	Format	Example
Production	tb_live_<hex>	tb_live_a1b2c3d4e5f6...
Development	tb_dev_<hex>	tb_dev_a1b2c3d4e5f6...
Test	tb_test_<hex>	tb_test_a1b2c3d4e5f6...

Managing API Keys

Operation	Endpoint
Create	POST /v1/api-keys
List	GET /v1/api-keys
Delete	DELETE /v1/api-keys/:id
Rotate	POST /v1/api-keys/:id/rotate

GraphQL API Authentication

Cognito User Pools

The GraphQL API uses AWS Cognito for authentication. After logging in via the login mutation, you receive tokens:

mutation {
  login(email: "[e-mail]", password: "password", recaptcha_token: "token") {
    ... on AuthPayload {
      accessToken
      refreshToken
      idToken
    }
    ... on TwoFactorRequired {
      user_id
      message
    }
  }
}

Send the access token in the Authorization header for subsequent requests.

API Key (AppSync)

Some queries support AppSync API key auth (marked with @aws_api_key in the schema). Pass the key via the x-api-key header.

OAuth Providers

TokenBot supports social login via the GraphQL API:

Provider	Mutation	Token Source
Google	google_auth(token)	Google OAuth token
Twitter/X	x_auth(token)	Twitter OAuth token
Apple	apple_auth(token)	Apple ID token

All return the same LoginResult type with access/refresh tokens.

Passkeys / WebAuthn

Passwordless authentication using FIDO2/WebAuthn:

1. Register: generatePasskeyRegistrationChallenge → registerPasskey(credential, device_name)

2. Login: generatePasskeyLoginChallenge(email) → loginWithPasskey(credential, recaptcha_token)

3. Manage: userPasskeys, renamePasskey, deletePasskey

Two-Factor Authentication (2FA)

TOTP-based 2FA:

1. Setup: generate_2fa → returns QR code/secret → enable_2fa(token) to confirm

2. Login: When 2FA is enabled, login returns TwoFactorRequired → call verify_2fa_code(user_id, token)

3. Disable: disable_2fa

Security Best Practices

• Never commit API keys to version control

• Rotate keys periodically via POST /v1/api-keys/:id/rotate

• Use the minimum required scopes

• Enable 2FA on your account