> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portal.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Explore with Postman

> Use the Portal.io API Postman collection to explore endpoints, test requests, and debug your integration without writing code.

Postman is a free application that lets you build, send, and inspect HTTP requests through a visual interface. Instead of assembling curl commands by hand, you fill in the URL, headers, and body in a form, hit **Send**, and see the full response — status code, headers, and body — right in the app.

For the Portal.io API, Postman is especially useful because every request requires HMAC-SHA256 signature headers. The Portal.io Postman collection includes pre-configured requests and a built-in pre-request script that computes signatures automatically, so you can focus on understanding the API rather than debugging authentication.

## Why use Postman with the Portal.io API

Portal.io's HMAC authentication means every request needs five headers and a correctly assembled signature. Getting any piece wrong produces a `401` with no detail about what failed. Postman eliminates that friction during development:

* **Pre-built requests** — every Portal.io API endpoint is already set up with the right method, URL, headers, and sample body. You just fill in your credentials.
* **Automatic HMAC signing** — the collection's pre-request script builds the canonical message and computes the Base64-encoded HMAC-SHA256 signature on every send. No manual signature work needed.
* **Instant feedback** — see the full response (status, headers, JSON body) immediately. Compare what you expect with what the API actually returns.
* **Environment variables** — store your Application Key, Secret Key, and User Key once, and they apply to every request in the collection.

## Get the collection

<Card title="Run in Postman" icon="play" href="https://god.gw.postman.com/run-collection/54258156-d5763440-1c26-4cff-9c73-76c347909aa1">
  Import the Portal.io API collection directly into your Postman workspace.
</Card>

If you prefer to import manually, copy this link and use **Import → Link** in the Postman app:

```
https://god.gw.postman.com/run-collection/54258156-d5763440-1c26-4cff-9c73-76c347909aa1
```

## Set up your environment

After importing the collection, create a Postman environment with the following variables. These are referenced by the collection's pre-request script and request templates.

| Variable    | Value                           | Where to get it                                                              |
| ----------- | ------------------------------- | ---------------------------------------------------------------------------- |
| `appId`     | Your API Application Key        | Provided by your Portal.io representative                                    |
| `secretKey` | Your Secret Key                 | Provided by your Portal.io representative                                    |
| `userKey`   | Your User API Key               | Returned by the credential exchange endpoint (see [quickstart](/quickstart)) |
| `baseUrl`   | `https://sandbox.api.portal.io` | Use `https://api.portal.io` for production                                   |

<Tip>
  Run the **API Key Exchange** request in the collection first. It returns your User Key, which you can copy into the `userKey` environment variable. After that, every other request in the collection will authenticate automatically.
</Tip>

## Make your first request

Once your environment variables are set:

1. Select the **List Proposals** request from the collection sidebar.
2. Confirm the environment dropdown (top right) is set to the environment you just created.
3. Click **Send**.

You should see a `200` response with a JSON body containing your proposals array. If you get a `401`, double-check that your `appId`, `secretKey`, and `userKey` variables are set correctly and that you selected the right environment.

## Tips for working with the collection

* **Duplicate before customizing.** If you want to modify a request (add query parameters, change the body), duplicate it first so the original stays intact for reference.
* **Check the console.** Open the Postman Console (View → Show Postman Console) to see the exact request that was sent, including the computed signature. This is invaluable when debugging authentication issues.
* **Switch environments for production.** Create a second environment with your production credentials and `baseUrl` set to `https://api.portal.io`. Switching between sandbox and production is a single dropdown change.

## Installing Postman

If you don't have Postman installed, download the free desktop app from [postman.com/downloads](https://www.postman.com/downloads/). Postman is available for macOS, Windows, and Linux. There is also a web version at [go.postman.co](https://go.postman.co) that works in any browser — no installation required.