Configure the app key
SetBANKROLL_APP_KEY on your server to a base58 Ed25519 secret key:
64 bytes containing the 32-byte seed followed by its matching public key.
Keep it separate from BANKROLL_TREASURY_KEY. The app key authenticates API
calls; it does not receive payments or sign payouts.
appAddress() from @joinbankroll/sdk/server derives the public key.
manifestRoute includes it as top-level appKey by default. The SDK selects
BANKROLL_APP_KEY, falling back to BANKROLL_PUSH_KEY only when the app
key variable is unset. An empty, malformed, or mismatched selected key fails;
it does not fall back to another key or the treasury.
Have Bankroll sign the manifest containing appKey, then set
BANKROLL_SIGNED_MANIFEST to that signed JWT. manifestRoute serves it verbatim.
Notifications also need a truthy capabilities.push;
matchmaking requires no additional capability.
Authenticate requests
Your server signs a short-lived JWT with the private key matching the signed manifest’sappKey. For app-authenticated endpoints at
https://api.joinbankroll.com, send Authorization: Bearer <app-jwt>.
The protected header is:
Bankroll allows five seconds of clock tolerance. The JWT must be at most
8 KiB. It authenticates app identity and can be reused across endpoints during
its lifetime; each endpoint checks its own permissions and JSON body. The SDK
creates these tokens for you. User session tokens and legacy notification-request JWTs
do not authenticate these general API calls.
Authentication failures return
{ "error": "unauthenticated" } (401),
app_not_verified (403), or unavailable (503). Each endpoint documents its
additional errors.
Rotate a key
Generate a replacement keypair in your app’s environment and have its public key re-signed in the manifest. Serve the replacement signed manifest and switch to its matching private key. A changed manifest re-asks connected users for consent. Bankroll caches verified manifests for five minutes. After changing a key, serve a newly signed manifest and allow for that cache window; replacing or removing the manifest does not promise immediate revocation of prior access.Legacy keys
Existing manifests with a public-key string incapabilities.push remain
supported. pushAddress() returns the same selected public key as
appAddress(), so existing push: pushAddress declarations still work.
If appKey is present, it must be valid and takes precedence over that legacy
string. Without appKey, notifications need a valid legacy key string; a boolean
alone is insufficient.
With only BANKROLL_PUSH_KEY, the SDK preserves the legacy notification request
format. Setting BANKROLL_APP_KEY selects shared app authentication for
notifications. Before switching, get a new signed manifest containing its appKey
and serve it verbatim. An existing signed manifest is never rewritten by
an SDK upgrade. See notification requests.