Customize your Run in Postman button

As an API publisher, you can dynamically inject information as environment variables into the Run in Postman button. You can customize and embed this button in your website’s client-side code so users can begin making calls to your API using Postman’s _pm() method. The Run in Postman button enables users who click it to fork your collection and environment into their Postman workspace.

Create a new environment

Create a new, empty environment using the env.create method:

1
_pm('env.create', 'environment_name', {key: value}, runButtonIndex);

Create a new environment using API keys entered by your user:

1
function () {
2
  var stagingKey = document.getElementById('staging-key-input').value,
3
    productionKey = document.getElementById('production-key-input').value,
4
    runButtonIndex = 0,
5
    envData = {
6
      stagingKey: stagingKey,
7
      productionKey: productionKey
8
    };
9
10
  _pm('env.create', 'API Keys', envData, runButtonIndex);
11
}

The env.create method returns the total number of environments associated with Run in Postman buttons on the page on success and false on failure.

Pass a user’s sign-in credentials

Create an environment that contains the user’s sign-in credentials:

1
_pm('env.create', 'Spotify', {
2
  user_id: 'spotifyuser',
3
  authorization: 'Bearer 1234xyzd'
4
});

Edit an existing environment

Update an environment using the env.assign method:

1
_pm('env.assign', 'environment_name', {key: new_value, new_key: value}, preventOverride, runButtonIndex);

This method works for environments included in the Run in Postman button on creation, or environments added using the env.create method.

Update an environment’s API keys:

1
function () {
2
  var stagingKey = document.getElementById('staging-key-input').value,
3
    productionKey = document.getElementById('production-key-input').value,
4
    preventOverride = true,
5
    runButtonIndex = 0,
6
    envData = {
7
      stagingKey: stagingKey,
8
      productionKey: productionKey
9
    };
10
11
  _pm('env.assign', 'API Keys', envData, preventOverride, runButtonIndex);
12
}

The env.assign method returns true on success and false on failure.

Replace an existing environment

Replace the entire contents of an environment using the env.replace method:

1
_pm('env.replace', 'environment_name', {key: value}, runButtonIndex);

The env.replace method returns true on success and false on failure.

Remove an existing environment

Remove an existing environment using the env.remove method:

1
_pm('env.remove', 'environment_name', runButtonIndex);

The env.remove method returns true on success or false on failure.

Use multiple buttons with separate environments

You can embed multiple buttons on a single page. To include a different environment for each Run in Postman button, enable the segregateEnvironments property:

1
_pm('_property.set', 'segregateEnvironments', true);

If you enable segregateEnvironments, you must use runButtonIndex in all _pm() methods to reference each button according to its position in your page DOM:

1
var runButtons = Array.prototype.slice.call(document.getElementsByClassName('postman-run-button')),
2
  runButtonIndex = runButtons.indexOf(elem);

Use the index for jQuery

Use the following to return a jQuery object containing an index of all elements matching the postman-run-button query:

1
var runButtonIndex = $('postman-run-button').index(elem);

The response contains the index location for all elements that match.

Get all environments

Use the get() method to retrieve all environments:

1
_pm('_property.get', 'environments');

This returns a response containing an array of the available environments:

1
[
2
  {
3
    "button_index": 0,
4
    "name": "env1",
5
    "values": [
6
      {
7
        "key": "testKey",
8
        "value": "testValue",
9
        "enabled": true
10
      }
11
    ]
12
  }
13
]

Next steps

After creating a Run in Postman button, you can share your API with users by creating documentation in a public workspace.

• To learn how to create API documentation in Postman, see Document your APIs in Postman.
• To learn how to add your documentation to your public workspaces, see Publish documentation in Postman.