> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tempinbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How JWT tokens and session cookies work in the TempInbox API.

## Overview

| Mechanism                         | Used for                       | How it's set                              |
| --------------------------------- | ------------------------------ | ----------------------------------------- |
| **Cloudflare Turnstile**          | Creating new addresses         | Required in browser; blocks raw API calls |
| **JWT** (`Authorization: Bearer`) | Per-address inbox access       | Returned by `POST /api/new_address`       |
| **`jwt` cookie**                  | Browser clients (same-origin)  | Set automatically as `HttpOnly` cookie    |
| **`session_id` cookie**           | Multi-inbox session management | Set automatically as `HttpOnly` cookie    |

***

## Cloudflare Turnstile

`POST /api/new_address` requires a valid Turnstile token (`cf_token`) when Turnstile is enabled. This protects against automated address creation abuse.

**What this means for you:**

<AccordionGroup>
  <Accordion title="Browser use (no action needed)">
    Turnstile runs automatically in the TempInbox UI. No manual steps required.
  </Accordion>

  <Accordion title="API automation — extract JWT from browser">
    The recommended approach for scripts and CI:

    1. Open [tempinbox.dev](https://tempinbox.dev) in a browser
    2. DevTools → Application → Cookies → copy the `jwt` cookie value
    3. Use it as `Authorization: Bearer <jwt>` in your scripts
    4. The JWT lasts **7 days** — reuse it across runs

    ```bash theme={null}
    # Use a pre-extracted JWT directly — no Turnstile needed
    curl "https://tempinbox.dev/api/mails?limit=10&offset=0" \
      -H "Authorization: Bearer <your-jwt-here>"
    ```
  </Accordion>

  <Accordion title="Self-hosted instances with Turnstile disabled">
    If you run your own instance with `CF_TURNSTILE_SECRET_KEY` unset, `POST /api/new_address` works without a `cf_token` and returns a JWT directly:

    ```bash theme={null}
    curl -X POST https://your-instance.com/api/new_address \
      -H "Content-Type: application/json" \
      -d '{}'
    # Returns: { "address": "...", "jwt": "eyJ..." }
    ```
  </Accordion>
</AccordionGroup>

***

## JWT Auth

After obtaining a JWT, authenticate all mail endpoints:

```http theme={null}
GET /api/mails?limit=10&offset=0
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
```

<Warning>
  JWTs are address-scoped. A JWT for `inbox-a@tempinbox.dev` cannot access emails for `inbox-b@tempinbox.dev`. Store one JWT per address in your test runner.
</Warning>

**JWT lifetime:** 7 days. After expiry, extract a fresh one from the browser.

***

## Cookie Auth (Browser Clients)

When using the API from a browser on `tempinbox.dev`, cookies are set automatically:

* `jwt` — address JWT, `HttpOnly`, `SameSite=Lax`, 7-day expiry
* `session_id` — session identifier, `HttpOnly`, `SameSite=Lax`, 30-day expiry

***

## Session Endpoints (No JWT Required)

These use the `session_id` cookie instead of a JWT:

* `GET /api/session/addresses` — list all addresses in session
* `POST /api/switch_address` — switch active inbox
* `POST /api/logout` — clear session

***

## No-Auth Endpoints

No authentication required:

* `POST /api/new_address` — create address (Turnstile required unless disabled)
* `GET /health_check` — service health

***

## Rate Limits

All authenticated endpoints are rate-limited per IP. If you hit `429 Too Many Requests`:

* Add 2–3 second delays between poll requests on `/api/mails`
* Avoid creating new addresses in tight loops
* Reuse JWTs across test runs — a JWT is valid for 7 days