Geldstuck supports two authentication models. For most integrations you’ll use API keys - they identify your tenant and are the only way to call server-to-server endpoints.

​
API keys (server-to-server)

Every API request includes your key pair as headers: Every request to a tenant-scoped endpoint must include your API key pair:
HeaderValue
x-api-keyYour publishable key, e.g. pk_live_...
x-api-secretYour secret key, e.g. sk_live_...
Content-Typeapplication/json
The tenant is resolved automatically from the key pair - you never pass tenantId in the URL or body.

​
Key types

PrefixPurposeWhere it’s safe
pk_live_... / pk_test_...Publishable key. Identifies your tenant.OK to ship in clients, logs, frontend code.
sk_live_... / sk_test_...Secret key. Authenticates the request.Server-side only. Never ship to browsers or mobile apps.
If a secret key leaks, revoke it immediately and create a new one. All requests signed with the revoked key return 401 authentication_error within 60 seconds.

​
Example

curl https://api.geldstuck.com/v1/tenants/add-user \
  -H "x-api-key: pk_live_51H..." \
  -H "x-api-secret: sk_live_51H..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Ada", "email": "ada@example.com"}'

​
User sessions (dashboard & end-user flows)

The dashboard and user-facing flows (hosted KYC, escrow acceptance) authenticate users with short-lived JWTs plus a session cookie. You don’t manage these directly - they’re issued by /auth/login and refreshed automatically by the dashboard.
If you’re building a customer-facing app that needs a user session, use Single Sign-On below rather than hand-rolling the JWT flow.

​
Single Sign-On (SSO)

For platforms that want to delegate authentication to their own identity provider, Geldstuck supports SAML 2.0 and OIDC. Contact sales to enable SSO on your tenant. Once enabled, your users are minted a Geldstuck session from your IdP - no password management on our side.

​
Which auth do I use?

You’re calling…Use
/tenants, /kyc, /transactions, /source-of-funds, /webhooks (your backend → our API)API keys
The dashboard at app.geldstuck.comYour Geldstuck login (or SSO)
Hosted verification flow in a user’s browser or mobile appShort-lived verification session token from POST /kyc/onfido
Webhook signature verificationWebhook signing secret (different from API keys)

​
Rotating keys

Keys should be rotated on a schedule and immediately after any suspected exposure.
1

Create the new key

POST /tenants/:tenantId/api-keys - returns a new pk_ / sk_ pair.
2

Deploy the new key alongside the old

Update your secrets manager. Keep the old key live so in-flight requests don’t fail.
3

Revoke the old key

POST /tenants/:tenantId/api-keys/:keyId/revoke. Revocation takes effect within 60 seconds.
Use one key per environment and per service. Fine-grained keys make revocation painless - you only break the one caller.