# 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:

```bash
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:

```bash
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:

```graphql
mutation {
  login(email: "user@example.com", 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