Skip to main content
KeyStone OS uses Auth0 for authentication. There are two authentication methods depending on your use case.

M2M tokens (platform integration)

M2M (Machine-to-Machine) tokens are for server-to-server communication where no human user is involved. Your backend exchanges its client_id and client_secret for a short-lived access token via the Auth0 Client Credentials flow. This is the primary authentication method for platforms calling the KeyStone API.
Environment resolution: Your M2M client ID is linked to a specific platform environment. The API automatically resolves which environment you are operating in based on your credentials. Scopes: M2M tokens carry scopes that define what operations are permitted:

User tokens (dashboard access)

For interactive KeyStone Dashboard access, users authenticate via Auth0 Organizations using PKCE flow. User tokens carry permissions instead of scope. Team members can be invited and managed in the dashboard under Members. Each member is assigned a role that controls which dashboard features they can access. Environment header: User tokens must include the X-Keystone-Environment header to specify which environment to operate in:
This is required because a user may have access to multiple environments (e.g. sandbox, production).

IP allowlisting

Environments can optionally restrict API access to specific IP addresses. When configured, only requests from allowlisted IPs are accepted for M2M tokens in that environment. Configure IP allowlists in the KeyStone Dashboard under Settings > Security. You can add individual IPs or CIDR ranges, each with an optional description. Ranges must be in canonical form: the address part must be the network address (use 203.0.113.0/24, not 203.0.113.47/24). A range with host bits set is rejected with a 422 explaining both valid alternatives, so an intended single host is never silently widened to the whole range. Single IPs without a prefix are accepted and stored as /32 (IPv4) or /128 (IPv6). A /0 range is rejected because it would match every address. The IP checked against the allowlist is derived through the platform’s confirmed reverse-proxy topology (the TRUSTED_PROXY_COUNT and TRUSTED_PROXY_CIDRS deployment settings). X-Forwarded-For values supplied by the caller are never trusted, so the allowlist cannot be satisfied by header spoofing.
When no IPs are configured, all addresses are permitted. Adding the first IP immediately restricts access to only allowlisted addresses.
Enforcement fails closed. On a deployment where TRUSTED_PROXY_COUNT has not yet been confirmed and set, the API trusts only the direct TCP peer address - behind a load balancer that is the load balancer itself - so every environment with a configured allowlist denies ALL of its M2M requests with 403 IP_NOT_ALLOWED until the setting is in place. If all your requests are rejected right after enabling an allowlist, this fail-closed state is the likely cause. Denials are logged server-side with the observed socket peer, and the operator checklist that must be completed before relying on allowlists in production lives on Settings.trusted_proxy_count in the API’s settings module.

Token lifecycle

Example: authenticated request

Next: Your first settlement

Walk through a complete settlement end-to-end.