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

# Authenticate Avalex API Requests with JWT Bearer Tokens

> Use JSON Web Tokens to authenticate Avalex API requests. Get a token via POST /auth/login, then include it as a Bearer token on every protected call.

JWT is the recommended authentication method for all Avalex API integrations. You exchange your username and password for a signed token once, then include that token on every subsequent request — no password is transmitted again. Tokens are valid for seven days, after which you simply log in again to receive a fresh one.

## How to Authenticate with JWT

<Steps>
  <Step title="Call POST /auth/login with your credentials">
    Send your username and password as a JSON body to the login endpoint.

    ```bash theme={null}
    curl -X POST http://localhost:8080/auth/login \
      -H "Content-Type: application/json" \
      -d '{"username": "ada", "password": "a-strong-password"}'
    ```

    A successful response returns a token and a summary of your account:

    ```json theme={null}
    {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "user": {
        "username": "ada",
        "isMasterAdmin": false,
        "permissions": ["customers:read", "customers:write"],
        "role": "Support"
      }
    }
    ```

    If your credentials are incorrect, the API returns a `401`:

    ```json theme={null}
    {
      "error": "Invalid username or password"
    }
    ```
  </Step>

  <Step title="Extract the token from the response">
    Copy the value of the `token` field from the response body. This is the JWT you will include in all subsequent requests.
  </Step>

  <Step title="Include the token in protected requests">
    Pass the token in the `Authorization` header as a Bearer token:

    ```bash theme={null}
    curl http://localhost:8080/customers \
      -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    ```
  </Step>

  <Step title="Re-authenticate after 7 days">
    Tokens expire after **7 days**. When your token expires, repeat the login call to receive a new one.
  </Step>
</Steps>

## Confirming Your Identity with GET /me

After logging in, you can verify which permissions your token carries by calling `GET /me`. This is useful for debugging access issues before making other calls.

```bash theme={null}
curl http://localhost:8080/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

The response returns your account details and the full list of permissions associated with your token:

```json theme={null}
{
  "username": "ada",
  "isMasterAdmin": false,
  "permissions": ["customers:read", "customers:write"],
  "role": "Support"
}
```

<Tip>
  Call `GET /me` immediately after login to confirm your permissions before making other API calls. This saves time when diagnosing unexpected `403` responses.
</Tip>

## Token Expiry and Renewal

JWT tokens are valid for **7 days** from the time they are issued. There is no refresh endpoint — when your token expires, call `POST /auth/login` again with your credentials to receive a new one. Your application should handle `401` responses by re-authenticating and retrying the original request.

<Warning>
  Store tokens securely. Do not log them, include them in URLs, or expose them in client-side code. Anyone who obtains your token can make API calls with your full permissions until it expires.
</Warning>