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

# Postman Collection

> Pre-built Postman collection for exploring and testing the KeyStone API with automatic Auth0 authentication.

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

| File                                                      | Description                                                                            |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Collection** (`keystone-api.postman_collection.json`)   | All platform API endpoints organized by resource, with example bodies and test scripts |
| **Environment** (`keystone-api.postman_environment.json`) | Variables for base URL, Auth0 config, and resource IDs                                 |

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](https://github.com/KeyStone-OS/keystone-api/blob/main/docs/postman/keystone-api.postman_collection.json)
* [keystone-api.postman\_environment.json](https://github.com/KeyStone-OS/keystone-api/blob/main/docs/postman/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

<Warning>
  Never commit your `client_secret` to version control. Postman stores current values locally and does not sync them to Postman Cloud by default.
</Warning>

***

## 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:

| Request                 | Saves variable        |
| ----------------------- | --------------------- |
| Submit instruction      | `instruction_id`      |
| Create settlement       | `settlement_id`       |
| Create webhook endpoint | `webhook_endpoint_id` |
| Create environment      | `environment_id`      |
| Create session token    | `session_token_id`    |

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:

| Variable         | Production                   | Staging                              |
| ---------------- | ---------------------------- | ------------------------------------ |
| `base_url`       | `https://api.keystoneos.xyz` | `https://api-staging.keystoneos.xyz` |
| `auth0_domain`   | `auth.keystoneos.xyz`        | `auth-staging.keystoneos.xyz`        |
| `auth0_audience` | `https://api.keystoneos.xyz` | `https://api-staging.keystoneos.xyz` |

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

<CardGroup cols={2}>
  <Card title="Use Collection Runner" icon="play">
    Run the entire collection in sequence to test a full settlement lifecycle from instruction to settlement events.
  </Card>

  <Card title="Duplicate for environments" icon="copy">
    Duplicate the Postman environment to maintain separate configs for production, staging, and local development.
  </Card>

  <Card title="Check the console" icon="terminal">
    Open the Postman Console (View > Show Postman Console) to inspect the Auth0 token request and debug authentication issues.
  </Card>

  <Card title="Fork the collection" icon="code-branch">
    Fork the collection in your Postman workspace so you can customize requests while still pulling updates from the source.
  </Card>
</CardGroup>