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

# Authentication

> How to authenticate with the Magne API using JWT tokens.

# Authentication

Magne uses **JWT (JSON Web Tokens)** for API authentication with a refresh token rotation scheme.

## Auth Flow

<Steps>
  <Step title="Register or Login">
    Call `POST /v1/auth/register` or `POST /v1/auth/login` to receive an initial token pair.

    ```json theme={null}
    {
      "token": "eyJhbGciOiJIUzI1NiIs...",
      "refreshToken": "550e8400-e29b-41d4...",
      "user": {
        "id": "...",
        "username": "example"
      }
    }
    ```
  </Step>

  <Step title="Use the Access Token">
    Include the `token` in the `Authorization` header for all authenticated requests:

    ```bash theme={null}
    Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
    ```
  </Step>

  <Step title="Refresh When Expired">
    Access tokens are short-lived. When expired, use the refresh token:

    ```bash theme={null}
    POST /v1/auth/refresh
    Content-Type: application/json

    {
      "refreshToken": "550e8400-e29b-41d4..."
    }
    ```

    This returns a **new access token AND a new refresh token** (rotation). The old refresh token is invalidated.
  </Step>
</Steps>

## Token Lifetime

| Token             | Lifetime              | Storage                      |
| ----------------- | --------------------- | ---------------------------- |
| **Access Token**  | Short-lived (minutes) | Memory only                  |
| **Refresh Token** | 30 days               | Secure storage, hashed in DB |

## Unauthenticated Endpoints

These endpoints do **not** require a Bearer token:

| Endpoint                        | Purpose                          |
| ------------------------------- | -------------------------------- |
| `POST /v1/auth/register`        | Account registration             |
| `POST /v1/auth/login`           | Login                            |
| `POST /v1/auth/verify-email`    | Email verification               |
| `POST /v1/auth/resend-code`     | Resend verification code         |
| `POST /v1/auth/forgot-password` | Password reset request           |
| `POST /v1/auth/reset-password`  | Password reset execution         |
| `POST /v1/auth/refresh`         | Token refresh                    |
| `POST /v1/webhooks/:id/:token`  | Webhook execution (token in URL) |
| `GET /v1/invites/:code/preview` | Invite preview                   |
| `GET /v1/health`                | Health check                     |