- Introduction
- Installing and updating
- Navigating Postman
- Sending your first request
- Managing your account
- Syncing your work
- Discovering templates
- Creating your first collection
- Creating a workspace
- Setting up your Postman app
- Importing and exporting data
- Troubleshooting app issues
- Building requests
- Authorizing requests
- Receiving responses
- Grouping requests in collections
- Using variables
- Managing environments
- Visualizing responses
- Specifying examples
- Using cookies
- Working with certificates
- Generating client code
- Troubleshooting requests
- Using the Collection Runner
- Scheduling runs with monitors
- Building request workflows
- Importing data files
- Working with your team
- Defining roles
- Requesting access
- Sharing your work
- Your Private API Network
- Commenting on collections
- Versioning APIs
- Using version control
- Using the API Builder
- Managing and sharing APIs
- Validating APIs
- Monitoring your APIs
- Setting up a monitor
- Viewing monitor results
- Monitoring APIs and websites
- Set up integrations to receive alerts
- Running Postman monitors using static IPs
- Troubleshooting monitors
- Monitoring FAQs
- Analyzing with reports
- Documenting your API
- Authoring your docs
- Publishing your docs
- Viewing documentation
- Using custom domains
- Publishing templates
- Publishing to the API Network
- Submission guidelines
- Managing your team
- Purchasing Postman
- Billing
- Configuring team settings
- Utilizing audit logs
- Onboarding checklist
- Migrating data between teams
- Intro to SSO
- Configuring SSO for a team
- Logging in to an SSO team
- Microsoft AD FS
- Custom SAML in Azure AD
- Custom SAML in Duo
- Custom SAML in GSuite
- Custom SAML in Okta
- Custom SAML in Onelogin
- Custom SAML in Ping Identity
- Migrating to the current version of Postman
Coding with Run in Postman
Some API publishers use Run in Postman buttons alongside their own API documentation. If users input data in a developer portal, for example, the Run in Postman API can dynamically inject this provided information as environment variable values into the embedded Run in Postman button.
The Run in Postman API uses the _pm()
method to create or modify environments in your website's client-side code through existing dynamic Run in Postman buttons.
As another example, you can use the API to pass login credentials to Postman:
_pm('env.create', 'Spotify', {
user_id: 'spotifyuser',
authorization: 'Bearer 1234xyzd'
});
Contents
- Creating a new environment
- Editing an existing environment
- Replacing an existing environment
- Using multiple buttons
- Next steps
Creating a new environment
Use the env.create
method to create a new environment:
_pm('env.create', 'environment_name', {key: value}, runButtonIndex);
env.create
cannot be used to create duplicate environments. Calls made with existing environment names will fail.
Create a new environment using API keys entered by your user:
function () {
var stagingKey = document.getElementById('staging-key-input').value,
productionKey = document.getElementById('production-key-input').value,
runButtonIndex = 0,
envData = {
stagingKey: stagingKey,
productionKey: productionKey
};
_pm('env.create', 'API Keys', envData, runButtonIndex);
}
The env.create
action will return true on success, false on failure.
Editing an existing environment
Use the env.assign
method to modify an environment:
_pm('env.assign', 'environment_name', {key: new_value, new_key: value}, preventDefault, runButtonIndex)
The
env.assign
method works for environments that were included in the Run in Postman button when it was created, or environments that were added using theenv.create
method.env.assign
cannot be used to create new environments. Calls made usingenv.assign
will fail if an environment does not already exist.
Update an environment's API keys:
function () {
var stagingKey = document.getElementById('staging-key-input').value,
productionKey = document.getElementById('production-key-input').value,
preventOveride = true;
runButtonIndex = 0,
envData = {
stagingKey: stagingKey,
productionKey: productionKey
};
_pm('env.assign', 'API Keys', envData, preventOveride, runButtonIndex);
}
The env.assign
action will return true on success, false on failure.
Replacing an existing environment
Use the env.replace
method to replace an entire environment:
_pm('env.replace', 'environment_name', {key: value}, runButtonIndex)
env.replace
cannot be used to replace an environment which does not exist.
Replace an environment:
// Existing environment named 'user_data'
{
auth_token: 'q4yugoiwqu4habddef3897ryq3891s',
user_id: '823',
session_data: {}
}
// Replace the 'user_data' environment
_pm('env.replace', 'user_data', {});
The env.replace
method will return true on success, false on failure.
Using multiple buttons with separate environments
You can embed multiple buttons on a single page. If you want to include a different environment in each button, enable the segregateEnvironments
property.
_pm('_property.set', 'segregateEnvironments', true);
If
segregateEnvironments
is enabled, you will have to userunButtonIndex
in all pm() methods to reference each button according to its position in your page DOM. BecausesegregateEnvironments
is disabled by default,runButtonIndex
is optional by default.
Including the index
If segregateEnvironments
is enabled, you'll have to use runButtonIndex
in all pm() methods to reference each button according to its position in your page DOM. The runButtonIndex
is represented by an integer.
var runButtons = Array.prototype.slice.call(document.getElementsByClassName('postman-run-button')),
runButtonIndex = runButtons.indexOf(elem);
Using the index for jQuery
var runButtonIndex = $('postman-run-button').index(elem);
Next steps
Learn how to create API documentation from Postman, and then add your documentation to Postman's API Network.