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

# Authentication

> Authenticate with the Leaf API using JWT tokens. Get a token, understand expiration and renewal, and see example requests in cURL, Python, and JavaScript.

Leaf uses JWT (JSON Web Token) authentication. You send your email and password to the authenticate endpoint, get back a token, and include that token as a Bearer header on every subsequent request.

## Get a token

Send a `POST` request to the authenticate endpoint:

```
https://api.withleaf.io/api/authenticate
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    -H 'Content-Type: application/json' \
    -d '{"username":"your-email@example.com","password":"your-password","rememberMe":"true"}' \
    'https://api.withleaf.io/api/authenticate'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.withleaf.io/api/authenticate",
      headers={"Content-Type": "application/json"},
      json={
          "username": "your-email@example.com",
          "password": "your-password",
          "rememberMe": "true"
      }
  )
  token = response.json()["id_token"]
  ```

  ```javascript JavaScript theme={null}
  const axios = require("axios");

  axios.post("https://api.withleaf.io/api/authenticate", {
    username: "your-email@example.com",
    password: "your-password",
    rememberMe: "true",
  })
    .then(({ data }) => {
      const token = data.id_token;
      console.log(token);
    })
    .catch(console.error);
  ```
</CodeGroup>

The response:

```json theme={null}
{
  "id_token": "eyJhbGciOi..."
}
```

## Token lifecycle

The `rememberMe` field controls how long your token lasts:

| `rememberMe` | Token duration |
| ------------ | -------------- |
| `"true"`     | 30 days        |
| `"false"`    | 24 hours       |

When a token expires, request a new one from the same endpoint. There is no refresh token flow; you re-authenticate with credentials.

## Using the token

Include the token in the `Authorization` header of every API request:

<CodeGroup>
  ```bash cURL theme={null}
  curl -H 'Authorization: Bearer eyJhbGciOi...' \
    'https://api.withleaf.io/services/usermanagement/api/users'
  ```

  ```python Python theme={null}
  response = requests.get(
      "https://api.withleaf.io/services/usermanagement/api/users",
      headers={"Authorization": f"Bearer {token}"}
  )
  ```

  ```javascript JavaScript theme={null}
  axios.get("https://api.withleaf.io/services/usermanagement/api/users", {
    headers: { Authorization: `Bearer ${token}` },
  })
    .then((response) => console.log(response.data))
    .catch(console.error);
  ```
</CodeGroup>

If the token is missing, expired, or invalid, the API returns a `401 Unauthorized` response.

## Multiple environments

Leaf does not provide separate test and production environments. Instead, create distinct API owner accounts for each:

* `leaf-test@yourcompany.com` for development and testing
* `leaf-prod@yourcompany.com` for production

Each API owner has its own token, Leaf users, configurations, and billing. This keeps test data isolated from production.

<Warning>
  Your contract may include a testing acre allotment. Make sure all test-related API calls use your test API owner account so testing usage is tracked separately.
</Warning>

## What to do next

* [Authentication API Reference](/api-reference/authentication): Endpoint details, request/response shapes, and error codes.
* [Quickstart](/getting-started/quickstart): Use your token to create a Leaf user and start pulling data.
* [Core Concepts](/getting-started/core-concepts): Understand the data pipeline before building.