> ## 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 by exchanging your API owner credentials for a JWT token, then include it as a Bearer token on all subsequent requests.

Leaf uses JWT (JSON Web Token) authentication. You exchange your API owner credentials for a token, then pass that token in the `Authorization` header of every request.

For conceptual background -- multiple environments, token usage patterns -- see [Authentication](/getting-started/authentication).

## Base URL

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

## Endpoints

| Action      | Method                                                           | Path            |
| ----------- | ---------------------------------------------------------------- | --------------- |
| Get a token | <span style={{fontWeight: 'bold', color: '#e5a00d'}}>POST</span> | `/authenticate` |

***

## Get a token

`POST /authenticate`

Exchanges API owner credentials for a JWT token.

### Request body

| Field        | Type   | Required | Description                                                                        |
| ------------ | ------ | -------- | ---------------------------------------------------------------------------------- |
| `username`   | string | Yes      | Your API owner email address.                                                      |
| `password`   | string | Yes      | Your API owner password.                                                           |
| `rememberMe` | string | No       | `"true"` for a 30-day token, `"false"` for a 24-hour token. Defaults to `"false"`. |

### Token duration

| `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.

### Request

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

### Response

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

### Using the token

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

```
Authorization: Bearer eyJhbGciOi...
```

### Error responses

| Status             | Meaning                                                                  |
| ------------------ | ------------------------------------------------------------------------ |
| `401 Unauthorized` | Credentials are invalid, or the token is missing, expired, or malformed. |