Postman Collection

The KeyStone Postman collection provides a ready-to-use set of API requests for every platform-facing endpoint. It includes automatic Auth0 token management, realistic example payloads, and response validation tests.

​

What’s included

The collection covers:

• Instructions - Submit, list, get, and cancel settlement instructions
• Settlements - Create, list, get, view events, and submit compliance decisions
• Templates - List and view settlement templates
• Webhooks - Full CRUD, test delivery, rotate secrets, view delivery history
• Environments - Create, list, get, update, and deactivate platform environments
• Sessions - Create and revoke frontend session tokens

---

​

Setup

​

1. Download the files

Download both files from the repository:

• keystone-api.postman_collection.json
• keystone-api.postman_environment.json

​

2. Import into Postman

1. Open Postman and click Import (top-left)
2. Drag both JSON files into the import dialog, or click Upload Files and select them
3. Click Import to confirm

​

3. Select the environment

1. In the top-right corner of Postman, click the environment dropdown
2. Select KeyStone API - Production

​

4. Set your credentials

1. Click the eye icon next to the environment dropdown to open the environment editor
2. Set the Current Value for:
   • client_id - Your Auth0 M2M client ID (from the KeyStone dashboard)
   • client_secret - Your Auth0 M2M client secret
3. If you have a specific environment ID, set environment_id as well

---

​

How authentication works

The collection uses a pre-request script at the collection level that automatically handles Auth0 M2M token management:

1. Before every request, the script checks if a valid access_token exists
2. If the token is missing or expired, it calls the Auth0 /oauth/token endpoint using your client_id and client_secret
3. The token is cached in the environment with a token_expiry timestamp
4. The token refreshes automatically 60 seconds before expiry

You never need to manually fetch or paste tokens. Just set your credentials once and every request authenticates automatically.

---

​

Using the collection

​

Typical workflow

A common exploration flow follows this order:

1. List templates - See what settlement templates are available
2. Create an environment (if you don’t have one) - Set up an isolated environment
3. Submit an instruction - Submit the seller side of a bilateral settlement
4. Submit the counter-instruction - Submit the buyer side (change role to buyer, direction to receive)
5. List settlements - The matched instructions create a settlement automatically
6. Get settlement by ID - View the settlement details and current state
7. Get settlement events - Watch the settlement progress through the state machine

​

Environment variables auto-populate

Several requests automatically save resource IDs to environment variables after a successful response: This means you can run “Create settlement” and then immediately run “Get settlement by ID” without manually copying the ID.

​

Customizing for staging

To point the collection at the staging API, update the environment variables: You can duplicate the environment in Postman to maintain both configurations side by side.

---

​

Response tests

Every request includes Postman test scripts that validate:

• Status codes - Each request checks for the expected HTTP status (201 for creates, 200 for reads, 204 for deletes)
• Response structure - List endpoints verify items and total pagination fields
• Resource fields - Detail endpoints check for expected properties like id, state, parties

Run the full collection with Postman’s Collection Runner to verify your integration end-to-end. Tests appear as green/red in the runner results.

---

​

Tips