Distributing API keys to every consumer that needs one is how most teams end up with secret sprawl. A single key gets copied into a shell profile, a .env file, a CI variable, and a shared password manager. Rotate it and something breaks. Revoke a person’s access and the key is still on their laptop somewhere.
Postman Passport takes a different approach. Instead of handing out the underlying secret, it hands out a credential reference: a token that points to a secret without containing it. The real key stays inside your own network, in your secret store. When a request goes through Passport, a proxy running inside your network resolves the reference, injects the actual credential, and forwards the request. The consumer never sees the key.
Postman Passport is available on Postman Enterprise plans with the Advanced Security Administration add-on. See the Postman pricing page for details.
In this post I’ll walk through the architecture: how credential references work, what happens on every request, the security properties Passport enforces, and how teams manage access through namespaces and roles. For the broader “why now” framing, the Postman Passport announcement post covers the product context.
What a credential reference actually is
A credential reference is a token that identifies a secret without containing it. When Passport grants a consumer access to an API, it issues the credential reference. The consumer places the reference into their request wherever the real secret would go. Whether that’s an Authorization header, a query parameter, or a body field, the reference behaves as a placeholder until the proxy resolves it.
References are cryptographically bound to the holder. If someone intercepts a reference in transit or copies it off a machine, it doesn’t work for them. The proxy checks the caller’s cryptographic identity before it resolves anything, and the private key that backs that identity never leaves the holder’s machine. A stolen reference without the matching key is inert.
That is the important shift. In a traditional API key model, possession of the key is authority. Anyone who gets the string can call the API. In the Passport model, the reference on its own has no authority. The authority is the cryptographic identity, and the reference is a pointer that only the identity’s holder can dereference.
The request flow
Here’s what happens when a consumer calls an API through Passport:
- The consumer sends a request with a credential reference in place of the real secret.
- The request routes through the secure access proxy running inside your network.
- The proxy authenticates the caller using a cryptographic certificate.
- The proxy checks whether the caller’s scope includes the referenced credential.
- If the check passes, the proxy resolves the secret from your secret store and injects it into the request.
- The proxy forwards the request to the destination and returns the response.
An example of what the consumer sees might look like this:
GET https://api.internal.example.com/v1/orders
Authorization: Bearer {{passport:cred_orders_read}}
That {{passport:cred_orders_read}} string is the credential reference. On the consumer’s machine, the Postman CLI sends the request through the local access proxy. The destination API sees a normal request with a real Authorization: Bearer <resolved-token> header. The consumer never had the resolved token.
The resolved secret never leaves the proxy. It doesn’t reach Postman, it doesn’t reach the application layer, and it doesn’t appear in any audit record.
The security model
Passport enforces several properties on every request. These are worth understanding because they shape how you reason about what Passport can and can’t protect against.
Identity is cryptographically proven. Each caller presents a certificate to the proxy, and the private key that backs the certificate stays on the caller’s machine. Identity can’t be forged. If a machine is compromised, that machine’s identity can be used from that machine, but identities can’t be lifted and reused elsewhere.
Scope is checked before resolution. The proxy verifies that the caller is authorized for the referenced credential before it contacts your secret store. If a caller tries to resolve a credential outside their scope, the proxy rejects the request without ever touching the store.
Secrets are resolved inside your network. The secure access proxy runs in the same private environment as your services. Secrets get read from your store, used to sign the outbound request, and then discarded. They don’t transit the Postman cloud, and they aren’t written to logs or audit records.
Passport uses your certificate authority as the trust root. Postman authorizes who can be issued a credential reference, but the certificates that prove caller identity are signed by your key. Team Admins can revoke access from your Private API Network at any time.
For teams in regulated industries like finance and healthcare, this design matters because it means secrets never cross an external network boundary. Third-party tools that terminate credentials outside your VPC are often disqualified by compliance policy. Passport keeps the resolution inside your network by design, which is one of the main reasons it fits into environments where other options don’t.
Team workflow: namespaces, managers, and members
Passport uses two roles inside a namespace to control who can add APIs and who can consume them.
Namespace Manager. Approves or denies workspace addition requests and API usage requests, and maps credential references to workspace environment variables. A Team Admin assigns this role.
Namespace Member. Can request to add a workspace so its APIs become available to others, or request access to an API they want to consume.
A typical setup flow looks like this:
- A Team Admin sets up the access proxy in Postman.
- The Team Admin creates a namespace and adds Namespace Managers and Namespace Members.
- A Namespace Member who produces an API requests to add their workspace to the namespace.
- A Namespace Manager approves the workspace request and maps credential references to the workspace’s environment variables.
- A Namespace Member who wants to consume an API requests access through the namespace.
- A Namespace Manager approves or denies each usage request.
- Approved Namespace Members connect to the access proxy from their machine using the Postman CLI.
- Approved Namespace Members send authenticated requests with their credential references.
Because access is granted per API and can be revoked at any time, you can offboard someone from a specific API without touching any other credential they hold. The reference stops resolving. There’s no key to rotate on the consumer side and no downstream distribution list to update.
Where Passport fits with your existing setup
Passport doesn’t replace your secret store. It sits in front of it. If you already use HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, or 1Password, the proxy resolves references against your existing vault of record. Rotation policies, audit trails, and access policies inside your vault continue to apply. Passport adds a distribution layer that keeps consumers from ever seeing the resolved values.
The consumer-side integration is the Postman CLI. Namespace Members connect the CLI to the local access proxy once, then call APIs from collections that reference passport variables the same way they’d reference any Postman variable. If you’re already writing test scripts that read environment values with pm.environment.get, you don’t rewrite them for Passport. The reference gets resolved on the way through the proxy.
What this changes in practice
The part I keep coming back to is offboarding. In a static-key world, revoking access means rotating the key and updating everyone who legitimately still needs it. If you missed a copy of the key in someone’s dotfiles, you find out when your monitoring picks up a call from a laptop that shouldn’t have one. With credential references, revoking access is a database write in your Private API Network. There’s no lingering copy of a secret on a former user’s machine, because there was never a secret on their machine to begin with.
The other thing worth noting is that this model works the same way for AI agents as it does for people. An agent running against an API through Passport gets a credential reference bound to its identity, with a scope you approved. When the agent is done, its identity is revoked and every reference it held stops resolving. You don’t have to trust that an agent’s process cleaned up its memory or logs, because it never had the secret to clean up.
Try it out
If you’re on the Postman Enterprise plan with the Advanced Security Administration add-on, the natural place to start is registering an access proxy and setting up a namespace with one API you’d like to onboard. Pick something with a static bearer token that a handful of consumers use today, since that’s the case Passport was designed to replace first.
If you’re evaluating whether Passport fits your architecture, the questions I’d start with: which of your APIs currently distribute static keys to consumers, and what would offboarding one of those consumers look like today? The APIs where the honest answer is “we’d probably miss a copy on someone’s laptop” are the ones where Passport pays for itself first.
Resources
The post How Postman Passport keeps API secrets inside your network appeared first on Postman Blog.
Log in
