# Using the Hyperproof Postman collection

The Hyperproof Postman collection provides a ready-to-use set of pre-built API requests for every endpoint in the Hyperproof API. It's a convenient way to explore and test the API without writing any code.

## Downloading the collection

Download the collection JSON file from here Hyperproof Postman Collection. The file is named `hyperproof-postman-collection.json`.

## Importing into Postman

1. Open Postman.
2. Click **Import** in the top-left corner.
3. Select **File** and choose the downloaded `hyperproof-postman-collection.json` file.
4. Click **Import** to confirm.


Once imported, the **Hyperproof API** collection will appear in your Collections panel, with requests organized by resource type (Controls, Issues, Users, etc.).

## Configuring collection variables

The collection uses variables for the base URL and authentication credentials so you don't need to edit individual requests. To set them:

1. In the Collections panel, click the **Hyperproof API** collection name.
2. Select the **Variables** tab.
3. Fill in the **Current Value** column for each variable:


| Variable | Description |
|  --- | --- |
| `base_url` | Pre-set to `https://api.hyperproof.app/v1`. Change this only if directed by Hyperproof support. |
| `client_id` | Your API client ID. |
| `client_secret` | Your API client secret. |
| `access_token` | Leave blank for now — you'll populate this after authenticating. |


1. Click **Save**.


To obtain a `client_id` and `client_secret`, you must first create an API client in your Hyperproof organization. Refer to [OAuth client credentials flow](https://developer.hyperproof.app/hyperproof-api/api-002-oauth-client-credentials-flow) for instructions.

## Obtaining an access token

The collection includes a pre-built **Get OAuth Access Token** request in the **Authentication** folder.

1. In the collection, open the **Authentication** folder and select **Get OAuth Access Token**.
2. Confirm the request body is pre-filled with `{{client_id}}` and `{{client_secret}}`.
3. Click **Send**.


If successful, the response will contain an `access_token`:


```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}
```

1. Check that the `access_token` variable is now populated.


All requests in the collection will now include this token automatically via the collection-level Bearer auth setting.

## Making your first request

1. Open any resource folder, for example **Controls**.
2. Select **Get Controls**.
3. Click **Send**.


A successful response returns a JSON array of controls from your organization.

## Notes and tips

- Access tokens expire after one hour. If you receive a `401 Unauthorized` response, repeat the steps in [Obtaining an access token](#obtaining-an-access-token) to get a fresh token.
- Path parameters such as `controlId` or `issueId` appear as `:controlId` in the request URL. Replace these with actual IDs before sending.
- Query parameters are included in each request but disabled by default. Enable and fill them in as needed using the **Params** tab.
- Never commit or share your `client_secret` or `access_token`. Treat them with the same care as a password.