Authentication - Zest Public API

The Zest Public API uses the OAuth 2.0 JWT-Bearer assertion grant (RFC 7523). Each call presents a short-lived bearer token; partners exchange a self-signed JWT to mint that token.

Flow

Build a JWT assertion

Sign a JWT with the EdDSA private key registered with Zest. Claims are listed below.

POST to /v1/oauth2/tokens

Body: grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<JWT>. Response: { accessToken, refreshToken, tokenType, expiresIn, refreshExpiresIn }.

Send the access token

Add Authorization: Bearer <accessToken> to every subsequent request.

Refresh before expiry

Default lifetime is 1 hour. Cache and reuse the access token; mint a new JWT only when the previous access token is expiring.

Required JWT claims

Claim	Description
`iss`	Your API base URL (acts as your issuer identifier).
`sub`	Your `client_id`.
`aud`	Zest API base URL of the environment you’re calling — exactly `https://public-api.zestequity.com` or `https://sandbox-api.zestequity.com`.
`client_id`	Your `client_id` (must match `sub`).
`iat`	Issued-at, unix seconds.
`exp`	Expiry, unix seconds. Keep short — 60 seconds is recommended.

The JWT MUST be signed with EdDSA. Other algorithms are rejected.

Token exchange request

POST /v1/oauth2/tokens HTTP/1.1
Host: public-api.zestequity.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<signed-JWT>

Successful response:

{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "refreshExpiresIn": 2592000
}

Refresh the access token

Each token exchange returns a long-lived refresh token (refreshToken, default lifetime 30 days). When your access token is close to expiring, redeem the refresh token for a fresh pair without re-doing the JWT assertion dance.

Refresh request

POST /v1/oauth2/tokens HTTP/1.1
Host: public-api.zestequity.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<your-refresh-token>

Successful response — same shape as the JWT-bearer grant:

{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "refreshExpiresIn": 2592000
}

Rotation semantics

The refresh token rotates on every use. As soon as we hand you a new pair, the previous refresh token stops working — store the new one immediately and discard the old one. If you ever try to redeem the old refresh token again (for example, after a crash that lost the new one), the call returns 401 and invalidates the entire chain. In that case, mint a fresh JWT assertion and re-do the JWT-bearer flow.

Common pitfalls

401 on a refresh that worked moments ago

The chain has been invalidated — usually because the previous refresh token was redeemed twice. Re-do the JWT-bearer flow to start a new chain.

When to refresh

Refresh proactively — for example, at half of expiresIn elapsed, or on the first 401 from an API call. Don’t wait until exactly iat + expiresIn; clock skew and request latency can cause edge-of-window failures.

Code samples

Python

import time
import jwt
import requests

CLIENT_ID = "client_xyz"
PRIVATE_KEY = open("ed25519-private.pem").read()
BASE_URL = "https://public-api.zestequity.com"

def mint_access_token() -> str:
    now = int(time.time())
    assertion = jwt.encode(
        {
            "iss": "https://your-api.example.com",
            "sub": CLIENT_ID,
            "aud": BASE_URL,
            "client_id": CLIENT_ID,
            "iat": now,
            "exp": now + 60,
        },
        PRIVATE_KEY,
        algorithm="EdDSA",
    )
    resp = requests.post(
        f"{BASE_URL}/v1/oauth2/tokens",
        data={
            "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
            "assertion": assertion,
        },
        timeout=10,
    )
    resp.raise_for_status()
    return resp.json()["accessToken"]

Node.js

import { SignJWT, importPKCS8 } from "jose";

const CLIENT_ID = "client_xyz";
const BASE_URL = "https://public-api.zestequity.com";
const PRIVATE_KEY_PEM = process.env.ZEST_PRIVATE_KEY;

async function mintAccessToken() {
  const privateKey = await importPKCS8(PRIVATE_KEY_PEM, "EdDSA");
  const now = Math.floor(Date.now() / 1000);

  const assertion = await new SignJWT({
    client_id: CLIENT_ID,
  })
    .setProtectedHeader({ alg: "EdDSA" })
    .setIssuer("https://your-api.example.com")
    .setSubject(CLIENT_ID)
    .setAudience(BASE_URL)
    .setIssuedAt(now)
    .setExpirationTime(now + 60)
    .sign(privateKey);

  const body = new URLSearchParams({
    grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
    assertion,
  });

  const res = await fetch(`${BASE_URL}/v1/oauth2/tokens`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body,
  });
  if (!res.ok) throw new Error(`token exchange failed: ${res.status}`);
  const json = await res.json();
  return json.accessToken;
}

Common pitfalls

invalid_token / 401 — clock skew

Zest tolerates only a few seconds of skew between your clock and ours. If your server clock drifts (common on bare-metal lab machines or some Docker hosts), JWT iat / exp checks fail. Fix by enabling NTP / chrony.

invalid_token / 401 — audience mismatch

The aud claim MUST exactly equal the base URL of the environment you’re calling. Sandbox tokens used against production (or vice versa) are rejected.

invalid_token / 401 — algorithm mismatch

JWT MUST be signed with EdDSA. RSA / HMAC assertions are rejected as a defence-in-depth measure.

invalid_token / 401 — sub != client_id

Both claims are required and must match each other. They identify the partner application.

Inspecting your token

curl https://public-api.zestequity.com/v1/oauth2/info \
  -H "Authorization: Bearer $TOKEN"

Returns metadata about the access token currently presented (client type, client id, application name).

​Flow

​Required JWT claims

​Token exchange request

​Refresh the access token

​Refresh request

​Rotation semantics

​Common pitfalls

​Code samples

​Python

​Node.js

​Common pitfalls

​Inspecting your token

Flow

Required JWT claims

Token exchange request

Refresh the access token

Refresh request

Rotation semantics

Common pitfalls

Code samples

Python

Node.js

Common pitfalls

Inspecting your token