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.

Pass a user's sign-in credentials

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

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

Create a new environment

Use the env.create method to create a new environment:

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

You can't use this method to duplicate environments. Any calls made using 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 method returns the total number of environments associated with Run in Postman buttons on the page on success and false on failure.

Edit an existing environment

Use the env.assign method to update an environment:

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

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

You can't use this method to create new environments. Any calls made using the env.assign method fail if the environment doesn't already exist.

To update an environment's API keys, use the following:

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 method returns true on success and false on failure.

Replace an existing environment

Use the env.replace method to replace the entire contents of an environment:

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

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

You can't use this method to replace an environment which doesn't exist.

Remove an existing environment

Use the env.remove method to remove an existing environment:

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

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

The environment must exist or this method will fail.

Use multiple buttons with separate environments

You can embed multiple buttons on a single page. If you want to include a different environment for each button, enable the segregateEnvironments property in the following:

_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:

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

Because segregateEnvironments is deactivated by default, runButtonIndex is optional by default.

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:

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

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

Get all environments

You can use the get() method to retrieve all environments:

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

This returns a response that contains an array of the available environments:

[
  {
    "button_index": 0,
    "name": "env1",
    "values": [
      {
        "key": "testKey",
        "value": "testValue",
        "enabled": true
      }
    ]
  }
]

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, visit Document your APIs in Postman.
• To learn how to add your documentation to your public workspaces, visit Publish documentation in Postman.