Skip to navigation
Use Passport

Call an API with Passport

As a Passport Member, you can send authenticated API requests using secret references instead of real secrets. This page covers how to send requests from the Passport CLI and external clients like curl and scripts.

To learn more about Passport roles, see Passport roles.

Prerequisites

Before you begin, make sure you have the following:

Copy a secret reference

Your requests use a secret reference token ({{vault:<id>}}) in place of the real secret. You can view every resource you can reach and when your access expires.

To copy a secret reference, do the following:

  1. In the left sidebar, select My access.
  2. Find the resource and expand its row to see its secret references.
  3. Click Copy next to a reference to copy its {{vault:<id>}} token.

Passport copies the reference token, never the secret itself.

Send a request from the Passport CLI

You can send requests directly using the Passport CLI. The Passport CLI handles mTLS directly, so no daemon is required. Use the secret reference name wherever the API requires a secret. This is the name the Admin set when mapping the secret reference, not the environment variable name. For all request options, see Request command.

For example, if the Namespace Manager mapped the secret reference POSTMAN_API_KEY to the api_key environment variable, use {{vault:POSTMAN_API_KEY}} in your request.

passport request "https://api.example.com/data" \
  -H "x-api-key: {{vault:POSTMAN_API_KEY}}"

Send a request from an external client

External clients like curl and scripts route requests through the local daemon at localhost:10144. Before sending requests, configure the ~/.passport/daemon.yml file to control which traffic the daemon intercepts. Then use the secret reference name wherever the API requires a secret. This is the name the Admin set when mapping the secret reference, not the environment variable name. The daemon resolves it at request time.

Configure daemon.yml

The passport setup command creates this file in forward-all mode. To change what the daemon intercepts, set one of the following modes:

Forward all — Routes every request through the proxy.

mode: forward-all

Allowlist (non-strict) — Routes only listed hosts through the proxy. Everything else goes direct.

mode: allowlist
strict: false
hosts:
  - api.example.com
  - "*.example-partner.com"

Allowlist (strict) — Routes only listed hosts through the proxy. Everything else is blocked with a 502.

mode: allowlist
strict: true
hosts:
  - api.example.com

Glob patterns are supported. Changes are picked up automatically without restarting the daemon.

NO_PROXY takes precedence over the daemon.yml file. Even if a host is in your allowlist or you’re using forward-all, a NO_PROXY match causes the request to bypass the daemon entirely. See Configuration notes.

Examples

With the daemon.yml file configured, use secret references wherever the API requires a secret. Secret references resolve in request headers and the URL.

curl:

curl "https://api.example.com/data" \
  -H "Authorization: Bearer {{vault:API_KEY}}"
# Header
curl -H "x-api-key: {{vault:API_KEY}}" https://api.example.com/data
# URL path
curl https://api.example.com/v1/{{vault:ACCOUNT_ID}}/transactions
# Query parameter
curl "https://api.example.com/search?token={{vault:ACCESS_TOKEN}}"

Node.js / TypeScript:

const response = await fetch("https://api.example.com/data", {
  headers: { "x-api-key": "{{vault:API_KEY}}" },
});
console.log(await response.json());

If fetch isn’t picking up the proxy, run your script with node --use-env-proxy your-script.js.

Configuration notes

If your HTTP client doesn’t respect HTTPS_PROXY or SSL_CERT_FILE, configure it manually to use http://127.0.0.1:10144 as the HTTPS proxy and trust the CA at ~/.passport/ca.pem.

Setup sets NO_PROXY to exclude Passport’s own backend domains (localhost, .postman.com, .getpostman.com, .pstmn.io, and others) so the daemon doesn’t loop its own backend calls through itself. If the API you’re testing is on an excluded domain, the request bypasses the proxy silently. To override this for a single request, clear NO_PROXY inline:

NO_PROXY="" curl "https://api.example.com/collections" \
  -H "x-api-key: {{vault:COLLECTIONS_API_KEY}}"

To override it permanently for a specific domain, remove that domain from NO_PROXY in your shell profile.