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

​
M2M tokens (platform integration)

For server-to-server integration, use Auth0 Client Credentials (M2M) tokens. This is the primary authentication method for platforms calling the KeyStone API. 
curl --request POST \
  --url https://auth.keystoneos.xyz/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://api.keystoneos.xyz",
    "grant_type": "client_credentials"
  }'
Environment resolution: Your M2M client ID is linked to a specific platform environment. The API automatically resolves which environment you’re operating in based on your credentials. Scopes: M2M tokens carry scopes that define what operations are permitted:
ScopeDescription
settlements:readView settlements and events
settlements:writeCreate settlements, submit compliance decisions
templates:readView settlement templates
templates:writeCreate and update templates
platform:readView platform details
platform:webhooks:manageManage webhook endpoints

​
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: 
X-Keystone-Environment: production
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.
When no IPs are configured, all addresses are permitted. Adding the first IP immediately restricts access to only allowlisted addresses.

​
Token lifecycle

PropertyValue
Token typeJWT (RS256)
Expiry24 hours
RefreshRequest a new token before expiry
Rate limitsContact support for current limits

​
Example: authenticated request

curl https://api.keystoneos.xyz/v1/settlements \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json"

Next: Your first settlement

Walk through a complete settlement end-to-end.