Developer key

Create a P-256 key in the app with its IP allowlist, load it on your server, and rotate it without downtime.

Your backend holds one credential: a P-256 private key. HEVN stores only the public half. That key logs you in to /dapi/v1 and signs the payments that leave your own integrator account. It never signs for a client: a client’s holder approves their own payouts in the sign-in window.

​

Create it in the app

Keys are created in the HEVN app — https://sandbox.gethevn.com, or https://app.gethevn.com in production — under Settings → Partner program → Developer. Nothing in this API creates one. The key opens a session that reaches every client linked to you, and it authorizes money from your own wallet, so creating it takes a browser session of your own, never a token this API minted.

Creation asks for one thing, the IP allowlist: the source addresses the key may be used from, 1 to 64 IPv4 addresses, IPv6 addresses or CIDR networks. It is frozen the moment the key exists. There is no edit and no PATCH; a new egress range means a new key.

The browser generates the keypair and shows you the private half once. Save it then: HEVN never holds it and cannot show it again. Write it to a file with mode 0600 on the machine that will use it, out of images, repositories and logs.

The app adds the public half to your own account’s signer in the same action, so there is nothing else to wire up. One key covers every client linked to you, because what it does for a client is authenticate your backend, not sign. An account can hold up to five keys at once, which is what makes a rotation possible without downtime.

​

What the key is

Property	Value
Curve	P-256, also called secp256r1 or prime256v1
Public key on the wire	base64 (standard alphabet, padded) of the DER SubjectPublicKeyInfo, at most 4096 characters
Signature on the wire	base64 of the ASN.1 DER ECDSA (r, s) over SHA-256 of the message
Fingerprint	sha256:<hex of sha256(DER)>
Key id	a dk_… id, shown in the app

PEM armor in a publicKey field is rejected, base64url is rejected, and a raw 64-byte r‖s signature — what WebCrypto and Java’s P1363 mode produce — is rejected. Convert to DER before you base64-encode. The details are in Signing.

​

What a session from the key may do

Every /dapi/v1 route is open to a session from any of your keys. What the key may sign is narrower, and it is fixed by whose wallet it is:

Operation	Who signs
A payout or swap from your integrator account	Your developer key, co-signed by HEVN — Signing
An operator action on an escrow deal you run	Your developer key, co-signed by HEVN — Escrow actions
A payout for a client	The client’s holder, in the sign-in window. Nothing for your key to sign

A confirm that would have your key sign for a client’s wallet answers 403 account_not_controlled. Nothing is prepared and nothing is signed.

The key caps nothing by amount. Whatever reaches your server with the key can spend all of your own wallet, and read and configure every client linked to you. Approval controls on your side are yours to build — see Accounts and control.

​

The IP allowlist

The allowlist is the set of source addresses the key may be used from. HEVN canonicalises every entry and drops duplicates, so 203.0.113.10 is stored as 203.0.113.10/32.

Every request re-checks it. A call from an address outside the list is 403, and so is a call whose source address HEVN cannot determine — on a read as on a payment.

The allowlist cannot be edited. Enter the addresses your deployment will actually call from, including the ones an autoscaler adds. A perfectly good key and a perfectly good signature still answer 403 from an address you did not list, and a new NAT gateway is an expensive way to find that out.

Your edge must strip caller-supplied X-Forwarded-For, X-Real-IP and CF-Connecting-IP before they reach HEVN, or the allowlist is checking a header the caller controls.

​

Load it in your server

Every example on these pages reads the key from HEVN_KEY_PEM — the file you saved when the app showed you the private half.

Python

import base64, os
from cryptography.hazmat.primitives import serialization


def load_key():
    with open(os.environ["HEVN_KEY_PEM"], "rb") as handle:
        return serialization.load_pem_private_key(handle.read(), password=None)


def public_key_b64(key) -> str:
    spki = key.public_key().public_bytes(
        serialization.Encoding.DER,
        serialization.PublicFormat.SubjectPublicKeyInfo,
    )
    return base64.b64encode(spki).decode()

A successful POST /dapi/v1/auth/challenge is the proof the key is live and the allowlist covers this host. See Sessions.

​

When a key is refused

Login answers the same refusal for every key problem — an unknown email, a key that no longer exists, a call from an address outside the allowlist, a signer that is not attached, a bad signature — so an attacker learns nothing from probing:

Status	code	What to check
401	invalid_credentials	The email, that the key still exists on the account, that you are calling from an allowlisted address, and that you signed the proof string with that key
400	request_expired	requestExpiry must be in the future and at most 5 minutes ahead

Once you are authenticated the refusals are specific, because by then HEVN knows who you are:

Status	code	Cause
403	forbidden	The key behind this session was deleted, or the request came from an address outside its allowlist. Every /dapi/v1 request re-checks both
403	forbidden, details.reason = "developerSessionRequired"	The bearer is not a platform access token — an ordinary API token, a refresh token, or a token with no key behind it
403	key_not_registered	The publicKey on a payment is not one of this account’s keys
403	account_not_controlled	The operation would sign for a wallet your key does not control — a client’s
409	signer_not_attached	The signer exists but is not attached to the wallet being spent from
400	signature_invalid	Wrong bytes or wrong encoding — see Signing

The full list is in Errors.

​

Rotate a key

Keys are immutable and additive, so a rotation is a roll rather than an edit, and both keys work while both are live.

1. Create the second key

   In the app, with an allowlist covering the hosts that will use it. Save the private half. Nothing changes for running code.

2. Switch your servers

   Deploy the new key file. Payments start carrying the new publicKey. An approval is bound to your signer rather than to one key, so anything prepared just before the switch can still be confirmed with either key while both are live.

3. Delete the old key

   In the app. The old key stops logging in and stops authorizing money on the next request that uses it.

Deleting a key does cut the sessions already minted from it. Every platform request re-reads the key, so the next call on an access token minted from a deleted key is a 403 — as is the POST /dapi/v1/auth/refresh that would have replaced it. That is the control to reach for when a token leaks, not only when a key does.

​

Habits worth keeping

• Keep the private key in a secret manager and mount it at runtime; keep it out of images, repositories and logs.
• One key per environment, and one per deployment if you can — the publicKey on each payment tells you which one signed.
• Give each key the narrowest allowlist its job allows, and create the replacement before you move traffic to a new range.
• Never sign in a browser. The key can spend your own balance and act on every client linked to you; a browser is the wrong place for it. The browser’s part is the sign-in window, which needs no key at all.
• Rehearse the roll before you need it. A rotation you have never run is not a control.

Next: Sessions

Two calls to log in, and one header to act as any of your clients.