Authentication

Every Leaf API request uses Authorization: Bearer <token>. There are two ways to get that token:

OAuth2 (recommended) — send your API owner email, password, and a Leaf-provisioned client_id to get an access_token and a refresh_token. Put the access_token in the Bearer header and call https://api-v2.withleaf.io. When it expires, exchange the refresh_token for a new access token without re-sending your password.
/authenticate — send your API owner email and password to get an id_token. There is no refresh token; when it expires, authenticate again. Call https://api.withleaf.io.

OAuth2

All token requests go to:

https://auth.withleaf.io/realms/leaf/protocol/openid-connect/token

Username/Password Grant

Uses your API owner email and password together with a client_id, sent with grant_type=password. Leaf provisions a client_id for you on request — contact your Customer Success representative to have it generated. Your existing logins continue to work unchanged.

cURL

curl -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password' \
  -d 'client_id=your-client-id' \
  -d 'username=your-email@example.com' \
  -d 'password=your-password' \
  'https://auth.withleaf.io/realms/leaf/protocol/openid-connect/token'

Never embed credentials in browser, mobile, or other client-side code, and always store access and refresh tokens securely.

Using and refreshing the token

The response contains an access_token and a refresh_token. Use the access_token in the Authorization: Bearer <token> header of every API request. When the access token expires, exchange the refresh_token for a new one without sending your credentials again.

When using OAuth2, send API requests to the new base URL https://api-v2.withleaf.io instead of https://api.withleaf.io.For example, Get All Leaf Users: https://api-v2.withleaf.io/services/usermanagement/api/users

For endpoint parameters, example requests per grant, and the full response and error shapes, see the Authentication API Reference.

Legacy `/authenticate` method

Email and password for an id_token. No refresh token. API calls go to https://api.withleaf.io. Send a POST request to the authenticate endpoint:

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

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'

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

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

The response:

{
  "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:

curl -H 'Authorization: Bearer eyJhbGciOi...' \
  'https://api.withleaf.io/services/usermanagement/api/users'

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

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

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.

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.

What to do next

Authentication API Reference: Endpoint details, request/response shapes, and error codes.
Quickstart: Use your token to create a Leaf user and start pulling data.
Core Concepts: Understand the data pipeline before building.

Getting Started

Configuration

Alerts

Leaf Users

Connecting Providers

Data Hierarchy

Machine Data

Satellite Imagery

Weather

Soil Sampling

Leaf Lake

UI Components

MCP Server

Irrigation

Beta

Administration

OAuth2

Username/Password Grant

Using and refreshing the token

Legacy `/authenticate` method

Token lifecycle

Using the token

Multiple environments

What to do next

​OAuth2

​Username/Password Grant

​Using and refreshing the token

​Legacy /authenticate method

​Token lifecycle

​Using the token

​Multiple environments

​What to do next

OAuth2

Username/Password Grant

Using and refreshing the token

Legacy `/authenticate` method

Token lifecycle

Using the token

Multiple environments

What to do next