Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.keystoneos.xyz/llms.txt

Use this file to discover all available pages before exploring further.

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. 
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 are 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
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.