Setting Up Plutora and Plutora Test API

The following article explains how to set up and test the Plutora API manually using Postman. See Visualize Plutora API With Swagger for the interactive Swagger API documentation.

You can also download the Plutora REST API Primer v1.4.1 and sample scripts.

For better performance, GET [entity] requests should use a paginated format. For example, GET releases?pageNum=0&recordsPerPage=100

For a full list of Plutora API functions, see the Plutora API help pages:

To set up access to API:

1a. Enable API in Plutora’s API Customization and generate a client_id and client_secret

API requests have a rate of throttling per API key to 26,000 requests per hour.

To enable the API:

  1. Go to Settings > Customization >Integrations.
  2. Click API – client_id & client_secret.
  3. Click to select the Enabled checkbox.
  4. Click Generate New Client Credentials.
  5. Copy and save the client_ID and client_secret.

    The content of these fields is machine-generated and cannot be edited.

 

1b. Enable API in Plutora Test’s API Customization and generate a client_id and client_secret

To enable the API of Plutora Test and generate API keys:

  1. Click Settings.
    Settings
  2. Click the Integrations tab.
  3. Click API.
    Plutora Test API Sept 8 2017
  4. Click to select the Toggle to enable/disable API access checkbox. The API Status will change to Enabled.
    Administrators need the API Access Permissions user permission to view this checkbox. Users who lack that permission will be able to see the API Status, API Client ID, and API Client Secret but will not be able to edit them.
  5. Click Generate New API Keys.
  6. Copy and save the API Client ID and API Client Secret.

 

2. Download and install Postman app

To download and install the Postman app:

  1. Go to https://www.getpostman.com/apps.
  2. Click the Download button for your platform. (Mac, Windows, or Linux.)
  3. Install Postman app:
    1. For Windows:
      1. Click the downloaded file to run the installer.
      2. Follow the prompts.
    2. For Mac:
      1. Double click to open the downloaded zip file.
      2. Drag the Postman app into your Applications folder.
    3. For Linux:
      1. Follow these instructions:
        https://blog.bluematador.com/posts/postman-how-to-install-on-ubuntu-1604/?utm_source=hootsuite&utm_medium=twitter&utm_campaign=

 

3. Retrieve a Token from the Authorization Server and test the connection

Tokens expire in 24 hours. After 24 hours, please create another token.

To use Postman app to retrieve a token from the authorization server:

  1. Click to open Postman app.
    Postman app
  2. Click Create basic request.
  3. Save your request by:
    1. Typing a Request name and Request description.
    2. Selecting a Collection.
    3. Clicking Save.
  4. Select Post from the Get drop-down menu.
  5. Select OAuth 2.0 from the Type drop-down menu under the Authorization tab.

    Plutora API does not allow No Auth. 
  6. Type the Request URL into the Enter request URL field.

    The Request URL for all of Plutora’s modules (including Plutora Test) is:
    https://[Country code: us, uk, au]oauth.plutora.com/oauth/token
    For example, US customers would type: https://usoauth.plutora.com/oauth/token
  7. Click the Body tab.
  8. Click to select the x-www-form-urlencoded radio button.
  9. Click the Key field and type or paste client_id.

  10. Click the Value field and paste in the client_id generated in step 1.
  11. Continue until you have added all the keys and values in the table below.
Key Value
client_id Paste the client_id generated from Plutora or Plutora Test.
client_secret Paste the client_secret generated from Plutora or Plutora Test.
grant_type Type “password”. (The actual word “password”, not your Plutora password.)
username Type the email address you use to log into Plutora or Plutora Test .
password Type the password you use to log into Plutora or Plutora Test.

Your screen should look like this:

  1. Click Send.
    After a few seconds of loading, the access token should appear.
    If using credentials from Plutora Test you may need to click Send a second time.

    Access token with arrows
  2. Copy and save the access token without the double quotes.
    If you get an error message instead, your Headers tab may not be blank. See the Troubleshooting section below.
  3. To test your API connection:
    1. Select Get from the Get drop-down menu.
    2. Click the Headers tab.
      Headers tab with arrow
    3. Click the Key field and type Authorization.
      Header tab key field with arrow
    4. Click the Value field and type bearer, type a space, then paste the access token.
      Your screen should look like this.
      Header tab with bearer and token
    5. Type the relevant URL below in the  Enter request URL field:
      Enter request URL field

      • US: https://usapi.plutora.com/me
      • UK: https://ukapi.plutora.com/me
      • AU: https://auapi.plutora.com/me
    6. Click Send.
      Your email address should appear.
      Email from API showing bearer

 

 

Use POST to copy a Release

PUT /releases, POST /releases, and POST /releases/bulk do not support the selection of Phase or Gate migration and therefore Activities related to the parent, associated TECRs, approvals, and so on are not adjusted. We recommend using the UI instead of the API when adding or updating a Release’s parent or child Release. 

For POST /releases the following business logic applies:

  • The Implementation Date can be in the past, present, or future.
  • The Release Status must not be in an End State.
  • Project and Independent Releases, but not Enterprise Releases, can be POSTed to.

To use POST to copy a Release (after following the instructions above):

  1. Find the ID of a Release to copy:
    1. Select Get from the Get drop-down menu.
    2. Type the relevant URL below in the  Enter request URL field:
      • US: https://usapi.plutora.com/releases?pageNum=0&recordsPerPage=100
      • UK: https://ukapi.plutora.com/releases?pageNum=0&recordsPerPage=100
      • AU: https://auapi.plutora.com/releases?pageNum=0&recordsPerPage=100
    3. Click the Headers tab.
    4. Click the Body tab under the Headers tab.
    5. Select Pretty and JSON if they are not already selected.
    6. Click Send.
      A high-level view of all the Releases will appear.
      GET Releases
    7. Find and copy the id of the Release you would like to copy.
  2. Show the Release you would like to copy:
    1. Type a / in the Enter request URL field, then paste the Release ID:
      • US: https://usapi.plutora.com/releases/ID
      • UK: https://ukapi.plutora.com/releases/ID
      • AU: https://auapi.plutora.com/releases/ID
        For example:
        https://ukapi.plutora.com/releases/3d6034e7-d531-42c7-b2d0-2d8341d624e6
    2. Click Send.
    3. Copy the Release data.
  3. Copy the Release:
    1. Select Post from the Get drop-down menu.
    2. Type the relevant URL below in the  Enter request URL field:
      • US: https://usapi.plutora.com/releases
      • UK: https://ukapi.plutora.com/releases
      • AU: https://auapi.plutora.com/releases
    3. Click the Body tab.
    4. Click to select the raw radio button.
      JSON (application/json) should be automatically selected. If not, select it manually.
    5. Paste the Release data into the top field.
    6. Make any changes you like to the data, for instance, adding the text Copy to the name field so that the name of the new Release is different.
    7. Click Send.
    8. Go to Release > Manager > Releases toggle button and search for your new copied Release.

 

 

An example script to download

Plutora REST API example.

 

Troubleshooting

Error: invalid_grant error_description: The client_id or client_secret is incorrect

If you receive the following error message while retrieving the access token:

{
 "error": "invalid_grant",
 "error_description": "The client_id or client_secret is incorrect."
 }

Solution: Your client_id and client_secret may have expired or been changed

Get a new client_id and client_secret by repeating the steps shown on this page under:
1. Enable API in Plutora’s API Customization and generate a client_id and client_secret.
Then repeat the steps under :
3. Retrieve a Token from the Authorization Server and test the connection.

 

Solution: Your Headers tab may not be blank

 

Your Headers tab may contain Key or Value data fields:

Header tab with bearer and token and arrows

Delete your Key or Value data fields so that your Headers tab looks like the following image and go through the steps of retrieving the access token again.

Headers tab as it should appear when retrieving an access token

 

 

Error: validation_error, error_description: Login failed, you have 5 attempts to login

If you receive the following error message while retrieving the access token:

{
 "error": "validation_error",
 "error_description": "Login failed, you have 5 attempts to login"
}

Solution: Check your username and password

You may have entered your username and password incorrectly.

Your user account may be locked if you enter your username and password incorrectly too often. Your administrator can unlock your account.

Wrong password API with arrow

 

 

Error: Could not get any response

If you receive the following error while retrieving the access token:

Could not get any response
There was an error connecting to https://oauth.plutora.com/oauth/token.
Why this might have happened:
-The server couldn't send a response:Ensure that the backend is working properly
-SSL connections are being blocked:Fix this by importing SSL certificates in Chrome
-Cookies not being sent:Use the Postman Interceptor extension
-Request timeout:Change request timeout in Settings  > General

Solution: Incorrect Enter request URL

You may have entered the Request URL incorrectly. Re-enter it and try again.

 

 

Error: The request entity’s media type ‘text/plain’ is not supported for this resource.

If you receive the following error while POSTing:

{
 "message": "The request entity's media type 'text/plain' is not supported for this resource."
}

Solution: Select JSON

JSON

Make sure that the raw type selected is JSON (application/json). Then hit Send again.

 

 

Back to the top arrow

Related Articles

Contents

Be the first to find out about new features. Subscribe to the Release Notes email.

Was this article helpful?

Thanks for your answer!