Skip to main content
Rhino.fi authenticates requests with a JSON Web Token (JWT). You get the token by exchanging an API key. Tokens are valid for one hour, so your integration should cache them and refresh them automatically.

Choose a key type

You create API keys in the Rhino.fi Console. There are two types, and the choice decides where a key may be used.
From 9 November 2026, SDA search and webhook event history accept only a JWT created from a secret key. Requests made with a public key are rejected with 403 SecretApiKeyRequired. Call these endpoints from your backend.
A secret key gives access to your project’s full transaction history. Never ship a secret key to a browser or mobile app, never commit it to source control, and store it in a secrets manager.

Restrict keys by IP

Both key types support an optional IP allowlist of up to five addresses. Requests from other IPs are rejected. The allowlist does not widen a key’s permissions: a public key with an allowlist still cannot read history. We recommend an allowlist on every secret key used in production. You manage allowlists in the Rhino.fi Console.

Get a JWT

Send your API key to the authentication endpoint.
The response contains a jwt field.

Send the JWT

Put the JWT in the Authorization header of every authenticated request. Both forms are accepted: the token on its own, or with a Bearer prefix (Bearer <jwt>).

Keep the token fresh

A JWT expires one hour after it is issued. Requesting a new token for every call adds latency, so cache the token and refresh it shortly before it expires. Every example in this section uses the helper below. Save it as rhino.js.
rhino.js
If a request returns 401 Unauthorized or 400 InvalidJwt, clear the cached token, request a new one, and retry once.

Next steps

Core concepts

Learn the identifiers, amounts, errors and limits shared by every endpoint.