Authentication

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

OAuth2 (recommended) — get an access_token from the Leaf token endpoint, put it in the Bearer header, and call https://api-v2.withleaf.io. Server-to-server integrations use an API client (client_id and client_secret) with the client credentials grant. Integrations that sign in with the API owner email and password use the password grant, and exchange the refresh_token for a new access token without re-sending the 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.

For conceptual background, see Authentication.

OAuth2 token endpoint

POST https://auth.withleaf.io/realms/leaf/protocol/openid-connect/token Requests use Content-Type: application/x-www-form-urlencoded. Three grant types are supported: client credentials, Username/Password, and refresh token.

Never expose credentials in browser or mobile clients, and store client secrets, access tokens, and refresh tokens securely.

Client credentials grant

Use this grant for server-to-server integrations. An API client belongs to one API owner, and its client ID starts with leaf-api-. Leaf provisions it and gives you the client_id and client_secret.

API clients do not accept the password grant: that request returns 400 unauthorized_client.
A new API client 403s until Leaf assigns its roles; the grant itself does not copy the API owner’s roles.

Field	Type	Required	Description
`grant_type`	string	Yes	`client_credentials`.
`client_id`	string	Yes	Your API client ID.
`client_secret`	string	Yes	Your API client secret.

curl -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=your-client-id' \
  -d 'client_secret=your-client-secret' \
  'https://auth.withleaf.io/realms/leaf/protocol/openid-connect/token'

import requests

response = requests.post(
    "https://auth.withleaf.io/realms/leaf/protocol/openid-connect/token",
    data={
        "grant_type": "client_credentials",
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
    },
)
token = response.json()["access_token"]

const axios = require("axios");

axios.post(
  "https://auth.withleaf.io/realms/leaf/protocol/openid-connect/token",
  new URLSearchParams({
    grant_type: "client_credentials",
    client_id: "your-client-id",
    client_secret: "your-client-secret",
  })
)
  .then(({ data }) => console.log(data.access_token))
  .catch(console.error);

The response has no refresh_token. The access token lasts 300 seconds (expires_in). Request a new token with the same grant before it expires. Calls made with the token act as the client’s API owner, limited to the permissions Leaf grants the client.

Username/Password Grant

Uses your API owner credentials together with a client_id that allows this grant.

Field	Type	Required	Description
`grant_type`	string	Yes	`password`.
`client_id`	string	Yes	The client identifier provisioned by Leaf.
`username`	string	Yes	Your API owner email address.
`password`	string	Yes	Your API owner password.

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'

import requests

response = requests.post(
    "https://auth.withleaf.io/realms/leaf/protocol/openid-connect/token",
    data={
        "grant_type": "password",
        "client_id": "your-client-id",
        "username": "your-email@example.com",
        "password": "your-password",
    },
)
token = response.json()["access_token"]

const axios = require("axios");

axios.post(
  "https://auth.withleaf.io/realms/leaf/protocol/openid-connect/token",
  new URLSearchParams({
    grant_type: "password",
    client_id: "your-client-id",
    username: "your-email@example.com",
    password: "your-password",
  })
)
  .then(({ data }) => console.log(data.access_token))
  .catch(console.error);

Refresh token grant

Exchange a refresh token for a new access token without re-sending credentials.

Field	Type	Required	Description
`grant_type`	string	Yes	`refresh_token`.
`client_id`	string	Yes	The client identifier.
`refresh_token`	string	Yes	The refresh token from a previous response.

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

import requests

response = requests.post(
    "https://auth.withleaf.io/realms/leaf/protocol/openid-connect/token",
    data={
        "grant_type": "refresh_token",
        "client_id": "your-client-id",
        "refresh_token": "your-refresh-token",
    },
)
token = response.json()["access_token"]

const axios = require("axios");

axios.post(
  "https://auth.withleaf.io/realms/leaf/protocol/openid-connect/token",
  new URLSearchParams({
    grant_type: "refresh_token",
    client_id: "your-client-id",
    refresh_token: "your-refresh-token",
  })
)
  .then(({ data }) => console.log(data.access_token))
  .catch(console.error);

Response

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOi...",
  "token_type": "Bearer"
}

Use the access_token in the Authorization: Bearer <token> header of every API request. When it expires, use the refresh token grant to obtain a new one.

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

Token lifetimes (expires_in, refresh_expires_in) are configured per client; the values above are examples and may differ for yours.

Error responses

Status	Error	Meaning
`400 Bad Request`	`invalid_request`	A required parameter is missing or malformed.
`400 Bad Request`	`invalid_grant`	Credentials or the refresh token are invalid or expired.
`400 Bad Request`	`unauthorized_client`	The client does not allow this grant type. For example, an API client (`leaf-api-…`) with `grant_type=password`.
`401 Unauthorized`	`invalid_client`	The `client_id` or `client_secret` is invalid.

Legacy `/authenticate` method

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

Base URL

https://api.withleaf.io/api

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

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

Response

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

Configuration

Leaf Users

Alerts

Providers

Data Hierarchy

Machine data

Satellite imagery

Weather

Soil Sampling

Leaf Lake

UI components

MCP server

Irrigation

Usage tracking

Beta

Authentication

OAuth2 token endpoint

Client credentials grant

Username/Password Grant

Refresh token grant

Response

Error responses

Legacy `/authenticate` method

Base URL

Request body

Token duration

Request

Response

Using the token

Error responses

​OAuth2 token endpoint

​Client credentials grant

​Username/Password Grant

​Refresh token grant

​Response

​Error responses

​Legacy /authenticate method

​Base URL

​Request body

​Token duration

​Request

​Response

​Using the token

​Error responses

OAuth2 token endpoint

Client credentials grant

Username/Password Grant

Refresh token grant

Response

Error responses

Legacy `/authenticate` method

Base URL

Request body

Token duration

Request

Response

Using the token

Error responses