Sessions

One developer key, two calls to log in, one header to act as a client.

Log in

Two calls, two signatures, no browser. POST /dapi/v1/auth/challenge proves you hold the key. Sign the proof string hevn-developer-key-login:{email}:{nonce}:{requestExpiry} with your developer key and send it with the public key you registered. nonce is any integer you have not used before; requestExpiry is a millisecond timestamp at most five minutes in the future.

{
  "email": "integrator@example.com",
  "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE…",
  "nonce": 481923756104,
  "requestExpiry": 1773679531000,
  "signature": "MEUCIQDk3f8Zc0xq2w1Yv7pB9nH4mJ6sR2tL5uD8aE0cQ1oXgAIg…"
}

The answer is a payload HEVN built for you:

{ "challengeId": "9f2c1ab8-4d7e-4f1f-a3c6-5b0e7d9a2c41", "payload": "eyJib2R5Ijp…", "expiresAt": "2026-09-17T10:06:10Z" }

POST /dapi/v1/auth/token exchanges your signature over that payload for a session. Sign the decoded bytes of payload, exactly as at payment time — Signing is the same mechanism.

{ "challengeId": "9f2c1ab8-4d7e-4f1f-a3c6-5b0e7d9a2c41", "signature": "MEQCIF3q…" }

Response

{ "accessToken": "eyJ…", "refreshToken": "eyJ…", "expiresIn": 3600, "userId": "cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41" }

The challenge is single-use and dies with its expiresAt: two /auth/token calls on one challengeId answer 409 challenge_consumed. userId is your own account’s id, and you can use it wherever a client id is accepted for your own account.

import os, secrets, time, httpx


def login(key) -> dict:
    api, email = os.environ["HEVN_API"], os.environ["HEVN_EMAIL"]
    nonce = secrets.randbits(48)
    expiry = int(time.time() * 1000) + 120_000
    proof = f"hevn-developer-key-login:{email}:{nonce}:{expiry}".encode()

    started = httpx.post(f"{api}/auth/challenge", json={
        "email": email,
        "publicKey": public_key_b64(key),
        "nonce": nonce,
        "requestExpiry": expiry,
        "signature": sign_bytes(key, proof),
    })
    started.raise_for_status()
    challenge = started.json()

    minted = httpx.post(f"{api}/auth/token", json={
        "challengeId": challenge["challengeId"],
        "signature": sign_payload(key, challenge["payload"]),
    })
    minted.raise_for_status()
    return minted.json()  # accessToken, refreshToken, expiresIn, userId

export async function login(key) {
  const api = process.env.HEVN_API;
  const email = process.env.HEVN_EMAIL;
  const nonce = Number(process.hrtime.bigint() % 281474976710656n);
  const expiry = Date.now() + 120_000;
  const proof = Buffer.from(`hevn-developer-key-login:${email}:${nonce}:${expiry}`);

  const post = async (path, body) => {
    const response = await fetch(`${api}${path}`, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(body),
    });
    if (!response.ok) throw new Error(`${path} ${response.status} ${await response.text()}`);
    return response.json();
  };

  const challenge = await post("/auth/challenge", {
    email,
    publicKey: publicKeyB64(key),
    nonce,
    requestExpiry: expiry,
    signature: signBytes(key, proof),
  });

  return post("/auth/token", {
    challengeId: challenge.challengeId,
    signature: signPayload(key, challenge.payload),
  });
}

func Login(key *ecdsa.PrivateKey) (Tokens, error) {
	api, email := os.Getenv("HEVN_API"), os.Getenv("HEVN_EMAIL")
	nonce := rand.Int63n(1 << 48)
	expiry := time.Now().Add(2 * time.Minute).UnixMilli()

	proof := fmt.Sprintf("hevn-developer-key-login:%s:%d:%d", email, nonce, expiry)
	proofSignature, err := SignBytes(key, []byte(proof))
	if err != nil {
		return Tokens{}, err
	}
	publicKey, err := PublicKeyB64(key)
	if err != nil {
		return Tokens{}, err
	}

	var challenge struct{ ChallengeID, Payload string }
	if err := PostJSON(api+"/auth/challenge", map[string]any{
		"email": email, "publicKey": publicKey, "nonce": nonce,
		"requestExpiry": expiry, "signature": proofSignature,
	}, &challenge); err != nil {
		return Tokens{}, err
	}

	payloadSignature, err := SignPayload(key, challenge.Payload)
	if err != nil {
		return Tokens{}, err
	}
	var tokens Tokens
	err = PostJSON(api+"/auth/token", map[string]any{
		"challengeId": challenge.ChallengeID, "signature": payloadSignature,
	}, &tokens)
	return tokens, err
}

Two tokens, two jobs

Token	Lifetime	Audience	What it is for
`accessToken`	1 hour (`expiresIn: 3600`)	`platform`	Every call: `Authorization: Bearer <accessToken>`
`refreshToken`	60 days	`platform-refresh`	One route only: `POST /dapi/v1/auth/refresh`, to mint a new access token

Both carry a developer_key_id claim naming the key registration that established the session, and the two audiences do not cross. /dapi/v1 refuses anything that is not a platform access token carrying that claim: no bearer at all is 401 unauthenticated, and an ordinary app token, a refresh token on a business route or a token with no registration behind it is 403 forbidden with details.reason = "developerSessionRequired". The ordinary /api/v1 refuses a platform token symmetrically, which is why the routes that register a developer key are not on this API — see Developer key. Re-mint with the refresh token as the bearer and an empty body:

curl -X POST "$HEVN_API/auth/refresh" \
  -H "Authorization: Bearer $HEVN_REFRESH_TOKEN" \
  -H "Content-Type: application/json" -d '{}'

minted = httpx.post(f"{os.environ['HEVN_API']}/auth/refresh", json={},
                    headers={"Authorization": f"Bearer {refresh_token}"})
minted.raise_for_status()
access_token = minted.json()["accessToken"]

const minted = await fetch(`${process.env.HEVN_API}/auth/refresh`, {
  method: "POST",
  headers: { authorization: `Bearer ${refreshToken}`, "content-type": "application/json" },
  body: "{}",
});
if (!minted.ok) throw new Error(`refresh ${minted.status}`);
const { accessToken } = await minted.json();

var minted hevn.Tokens
err := hevn.PostJSON(os.Getenv("HEVN_API")+"/auth/refresh", map[string]any{},
	&minted, hevn.Bearer(refreshToken))
accessToken := minted.AccessToken

Response

{ "accessToken": "eyJ…", "expiresIn": 3600, "userId": "cl_9f2c…" }

This is the one call that does not go through the client: it carries the refresh token, not the access token. The reference client wraps it in a Session so the request layer never thinks about expiry. Log in once per process, keep the refresh token in your secret store, and re-mint the access token about a minute before it expires. A refresh token is not an API credential: sent to any other route it is refused.

Acting as a client

Send X-Hevn-Account: cl_… alongside your own access token, and the call reads and writes that client. On most routes you may omit it, and the same call acts on your integrator account; on the singular /client* routes the header is required, so reading your own account there means sending your own cl_…. One token covers every client you control, so there is nothing to cache per client.

curl "$HEVN_API/transactions?limit=20" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: cl_7YQ2Kf3mN8"

rows = hevn.acting_as("cl_7YQ2Kf3mN8").get("/transactions", {"limit": 20})

const rows = await hevn.actingAs("cl_7YQ2Kf3mN8").get("/transactions", { limit: 20 });

rows, err := api.ActingAs("cl_7YQ2Kf3mN8").Get("/transactions", hevn.Query{"limit": "20"})

No path names a client any more — there is no {clientId} parameter left in the API — so the header is the only thing that selects an account, and each route treats it one of four ways:

Routes	The header
`/banks`, `/payins`, `/payouts`, `/contacts`, `/transactions`, `/documents`, and the `/sandbox/*` routes	Accepted, optional. Without it the call acts on your account
`GET /client`, `PATCH /client`, `GET /client/balance`, `GET /client/kyb`, `PUT /client/kyb`, `POST /client/kyb/complete`	Required. These are the singular, acting client; the header is the selector, including when the account you want is your own
`POST /clients`, `GET /clients`	Refused. The collection is yours by definition
All of `/escrow*`	Refused. A deal names `senderClientId` and `receiverClientId` in the body; the operator is always you
`/auth/*`	Ignored. A login has no account to act for yet, so the header is neither read nor refused

Sending the header where it is refused is an error rather than a silent no-op, so you find out in development:

Status	`code`	Cause
400	`account_header_invalid`	The value is not a `cl_…` client id
400	`account_scope_conflict`	The route is self-scoped: you sent the header to `/clients` or `/escrow*`, or you used a token that was already acting for another account there. `details.reason` is `selfScopedRoute`
422	`validation_failed`	The header is missing on a `/client*` route, where it is required. `details.fields` names it
404	`account_not_found`	Not one of your clients — unknown and foreign are indistinguishable on purpose
403	`account_forbidden`	The client exists and is yours, but your integrator standing or the relationship is not current

POST /dapi/v1/auth/refresh also accepts {"userId": "cl_…"} and mints an access token scoped to that one client. It still works, and it is no longer the documented path: it costs one token mint per client per hour and buys nothing the header does not give you.

What a session is bound to

An environment. Sandbox tokens are refused in production and the reverse.
The key registration behind it, on every single request. The developer_key_id in the token is re-read before the request is served: the registration must still be active, and the call must come from an address inside its immutable allowlist. Pausing a registration therefore does cut the tokens already minted from it — the next call is a 403, and so is the refresh that would have replaced it. See Developer key.
A set of source addresses. A deploy from a new egress IP fails every call with 403 even though the key, the signature and the token are all correct.
A budget. Reads and writes are limited per credential, and login has its own per-IP and per-email windows — over them is 429 with Retry-After. The numbers are in Limits. Logging in on a loop is the fastest way to lock yourself out; log in once and re-mint.

Next: Conventions

The seven rules that hold for every operation: money, ids, casing, idempotency, pagination, status codes, errors.

Start here

Core concepts

Onboard a client

Move money

Escrow

Ship it

Reference

Log in

Two tokens, two jobs

Acting as a client

What a session is bound to

Next: Conventions

​Log in

​Two tokens, two jobs

​Acting as a client

​What a session is bound to

Next: Conventions

Log in

Two tokens, two jobs

Acting as a client

What a session is bound to