Skip to main content
Each request to /v1 uses an API key. An org admin makes the key in the Hermes portal, under Integration → API keys. Send the key as a bearer token:

​
Keys

  • A key has no internal structure: jz_live_ and then a long random body. Only the first 16 characters show again. These characters are the prefix, for example jz_live_AbC123Xy. The prefix shows in your portal, in audit trails, and in support conversations. Use the prefix to identify a key to Jenzy.
  • The portal shows the full key one time only, when you create it. You cannot get the key again. Put the key in your secrets manager now. If you lose a key, make a new key and revoke the old key.
  • Your org can hold a maximum of 3 active keys. At that limit, the portal disables the Create key button. Revoke a key that you do not use to make a slot free.
  • Each key starts with jz_live_, in the sandbox and in production. Hermes does not make jz_test_ keys. The prefix does not tell you the environment. The base URL selects the environment. A sandbox key operates only against api.sandbox.jenzy.com. See Test in the sandbox.
Your key can spend your balance. Do not put the key in client-side code, in logs, or in URLs. If you think that a key leaked, revoke it in the portal at once. A revocation is immediate. Then tell Jenzy.

​
Key rotation

Your org can hold more than one active key at the same time. So a rotation is an overlap, and not a single event.
  1. In the portal, open Integration → API keys.
  2. Select Rotate on the key. The portal makes the replacement key first.
  3. Change your systems to the new key.
  4. Select Revoke on the old key.
The old key stays valid until you revoke it. So your org always has a key, and you do not need to plan a period of downtime. A rotation makes a key before it removes one. If your org holds 3 active keys, revoke a key that you do not use first.

​
IP allowlist (optional)

An org admin can limit your key to an exact list of IP addresses. The list is in the Hermes portal, under Integration → IP allowlist. If the list is not empty, a request from a different address gets 403 forbidden. The key alone is then not enough. Each entry is one exact IPv4 or IPv6 address. The list does not accept CIDR ranges. Only a portal session can change the list. An API key cannot change the list. So a person who steals a key cannot add an address to the list.

​
Rate limits

Hermes applies a rate limit to each org. Above the limit, you get this body:
The response is HTTP 429. The response also has a Retry-After header, in seconds. Obey the header and decrease your request rate. If you read GET /balance and GET /payouts/{id} at a moderate rate, you stay below the limit. org_limit_exceeded is different. That code is a limit on the number of new payouts, and not a limit on the number of requests. See Errors.