Postman <> Interceptor Integration
Update: This post was updated on June 22, 2019, following the release of this feature in Postman’s production build.
We’re finally ready to launch a beta for the Interceptor integration for the native Postman apps! The Interceptor is a very useful part of the Postman workflow - making API calls in the context of the browser’s session is a common use case. However, with Google announcing their intention to deprecate Chrome Apps, we realized that lack of this workflow was a big handicap for our native apps. Any use-case which requires you to login to the browser (effectively setting a cookie) and performing API calls from Postman was cumbersome at best. This is the first problem we’ve tried to address. The Interceptor integration in available in Postman starting today!
- Postman Interceptor (v0.2.26 and above): https://go.pstmn.io/interceptor-download
- Postman App (v7.2.1 and above): https://www.getpostman.com/downloads/
- Interceptor Bridge (available here):
Run the install script from the OS-specific Interceptor Bridge package. Do not change the location of the
com.postman.postmanapp.jsonfile after executing the install script. Depending on your OS, you might need to double-click or execute the installer script via a shell. Users on MacOS/Windows might see a security warning. For example, to override the security on MacOS, you may need to right click > open.
Restart Chrome (only required for Windows)
Update the Postman Interceptor Extension to v0.2.26 or above (
Developer Mode> Update).
Update Postman to v7.2.1 or above.
Open the capture cookie overlay from the icon on the top-right.
The ‘Interceptor Connected’ status indicates that Postman is able to communicate with the Interceptor extension installed in the browser.
Capture cookiessetting, and add domains you want to sync cookies for.
We’re using Chrome’s nativeMessaging feature to facilitate communication between the Interceptor (a Chrome Extension) and Postman (a native application). This requires a standalone executable to be present on the user’s system for Chrome to interact with. A detailed explanation of this flow is coming soon!
This means there’s a small installation step required before the integration can be used. You’ll need to download an OS-specific version of the bridge. The installer script will add an entry (certain file directories for OSX/Linux, Registry for Windows) that tells Chrome where to find the bridge executable.
The next time Chrome opens (and the Interceptor extension is enabled), the Interceptor will have a permanent duplex messaging link with this executable. The executable starts an IPC server, to enable communication between Postman and the executable.
To start using the cookie capture functionality, open the cookie capture overlay from the top-right of the Postman window. Here, you’ll be able to view and modify the list of domains you want to sync cookies for. You’ll also see the status of the Postman <> Interceptor connectivity. If you see an ‘Interceptor Disconnected’ status, try reinstalling the bridge, and restarting Chrome.
Once you see a successful connection, enable the
Capture cookies setting. You now need to add domains whose cookies you want synced from the browser. Entering the root domain will sync cookies for all its subdomains as well. Adding
facebook.com, for example, will sync cookies whose domain is
API reference (not required for Postman versions 7.2.1 and above):
pm.interceptorBridge.cookieSync.enable(): Enable cookie syncing from the Interceptor to Postman
pm.interceptorBridge.cookieSync.disable(): Disable cookie syncing from the Interceptor
pm.interceptorBridge.cookieSync.addDomain(domain: String): Add a new domain for which cookies should be synced. eg.
pm.interceptorBridge.cookieSync.removeDomain(domain: String): Stop receiving cookie updates for a domain.
pm.interceptorBridge.cookieSync.getDomainList(): Get the list of domains for which cookies are currently being synced
pm.interceptorBridge.setKey(key: String): Set a key for encryption over IPC. The same key must be set on the Interceptor as well. Using this is optional.
pm.interceptorBridge.getKey(): Reading the key that’s currently used for encryption over IPC.
The interceptor and Postman communicate via two sets of IPC. One provided by Chrome (from the Interceptor to the Bridge), one from the bridge to Postman. You can choose to set a key for end-to-end encryption of your messages.
If you set a key for encryption, use the
pm.interceptorBridge.setKey(key: String) command in the app. To set the key on the interceptor, open the Interceptor extension popup from the toolbar,
right click > Inspect Element > Console. Enter the same command here -
pm.interceptorBridge.setKey(key: String). This will encrypt anything sent between the two sides using AES.
Postman’s cookie jar will respect all cookie properties - expiry, path, secure etc.
For a domain that has cookie syncing enabled, new cookie creations, updates to cookie values/properties, and cookie deletions will all be synced to Postman.
Enabling cookie sync for
facebook.comwill enable cookie sync for all subdomains as well. Internally, we check for the domain strictly matching
facebook.com, or ending with
Once you disable cookie syncing for a domain, syncing of future cookie updates will be stopped, but the existing cookies for that domain will NOT be removed from Postman. They can be deleted manually from the Cookies section.
On restart of the Postman app, all cookies for the configured domains will be re-synced, so you’ll be able to retain browser context seamlessly.