Best Practices from Oracle Development's A‑Team

Invoking OCI REST APIs using POSTMAN

Oracle Cloud Infrastructure (OCI) is Oracle's next generation IaaS platform that enables building and running a wide range of applications and services in a highly available, hosted environment. OCI offers high-performance compute, storage, overlay virtual network, database, load balancing and numerous other capabilities.

One of the best features of OCI is that it uniformly presents all of its capabilities through the OCI UI Console, SDK, CLI and REST API.

In this blog we will explore how to invoke OCI REST APIs, and examine OCI's REST authentication scheme in detail. I will also provide a sample POSTMAN Collection and Environment script that automates most of the messy details and allows us to seamlessly call OCI APIs. 

If the reader is interested in invoking OCI REST API through cURL, please see my colleague Michael Shanley's blog here



In order to use any of the SDK, CLI or REST API, OCI has a few pre-requisites:

  1. Only an IAM User can can invoke the API. So make sure the users are created.

  2. Generate an RSA key pair and its fingerprint, as mentioned here .

  3. Make note of your OCI tenancy's OCID and the specific user's ( created in #1 above) OCID, as described here .

  4. Upload the generated RSA public key from the key pair , as described here .

  5. Generate the required header and authentication bits and invoke the API.

The steps 1-4 above are relatively straightforward.

Step 5 is already done for you if using the SDK or CLI, but the authentication pieces need to be constructed manually if invoking REST APIs manually, and that is what this blog post is mainly about.

In the sections below we will first understand the authentication scheme for invoking the OCI REST APIs, and then we will explore how we use POSTMAN to invoke the API.


OCI API Authentication Scheme

PS: Clients invoking OCI CLI or REST APIs cannot have its clock skewed more than 5 minutes from OCI, otherwise a 401 unauthorized error will be thrown.

PPS: OCI REST APIs require SSL TLS1.2 protocol.

OCI uses the IETF-draft-cavage-http-signatures-08 specification as its authentication scheme, which guarantees that the client is authenticated and the message integrity is preserved (HTTPS or SSL establishes confidentiality).

Understanding the above authentication scheme is a little challenging, below is a summary of the core requirements: 

  1. Generate Current Date

  2. Generate API_Key as “tenancyOCID/UserOCID/APIKeyFingerprint”

  3. Generate Signing String

    1. If POST/PUT , generate SHA256, base64 encoded hash of the body and include as part of signing string .

  4. Generate RSA Digital Signature of the SHA256 hash of the Signing String generated above.

  5. Set the formatted Authorization header that includes API Key, Digital Signature(from above step) and other parameters.

  6. Invoke the API with ‘Authorization’, ‘Date’, ‘Content-Type’, and ‘x-content-sha256’ hash of the body(3.a) as Header parameters.


Using POSTMAN to invoke OCI APIs

Postman is a GUI-based REST API invocation tool that is very popular among developers. However, even though Postman provides a lot of features, using the authentication scheme above for OCI REST APIs can be challenging.

Thankfully Postman allows automating such custom requirements using Sandboxes, Collections, and Environments.

Hence, I provide some scripts and steps below that can be used to allow invoking OCI REST APIs through Postman . Please follow the steps in the order described.

  1. Download the Postman Collections and Environment from github

  2. Import the environment into Postman using the 'Import' button at the top, and activate it by selecting it from the top right drop-down as shown below

  3. Open and Edit the newly imported environment, and set the variables tenancyId, authUserId, keyFingerprint and private Key. These are same as what we collected in the Basics section above.Also, make sure to set both Initial Value and Current Value of the variables. 

  4. Now import the two collections into Postman. 

  5. From the OCI_REST_INITIALIZATION collection, invoke the Initializer GET for 'jsrsasign-all-min.js' , which imports and initializes a required library jsrsasign for encryption and digital signatures. This is a one-time setup task. 

That's it. Now you can use the other oci_rest_collection to invoke any OCI REST APIs. The collection provides a sample GET and POST request, which can be extrapolated to invoke any OCI REST API. 

Just make sure that the OCI REST calls are executed as part of the OCI_REST_COLLECTION, as that collection contains the necessary javascript code to generate OCI's authentication header

Join the discussion

Comments ( 14 )
  • Abhijit Tuesday, June 4, 2019
    Thanks Ashish. This blogs is helpful and worked fine for me. One point worth mentioning is that the pre-request script will work only in the Postman Windows app. I first tried it in the Chrome Add-on app which didn't work. Anyways, Chrome app is deprecated recently.
  • Ashish Singh Wednesday, June 5, 2019
    Thanks for the feedback Abhijeet.
    I did not test the app using Chrome add-on, and you are right, the global variables may not be set correctly on the add-on postman.

    But as you say this is not an issue anymore as the add-on postman app is now deprecated.
  • VINAY AGARWAL Monday, July 15, 2019
    While i tried this i get the following error in postman app. Any suggestion?

    There was an error in evaluating the Pre-request Script: ReferenceError: KJUR is not defined
  • Eugene Monday, August 5, 2019
    Thanks very very much for the nice info
  • Rajat Gupta Wednesday, August 7, 2019
    Hi Ashish- Thank you for this post. Very nicely done!

    Request: It seems that the headers don't get pre-populated for new requests using the OCI environment. Can you please see if there's a way to achieve that? Thanks again!
  • Ashish Singh Wednesday, August 7, 2019
    Great feedback Rajat.
    I've made changes to the repository to make sure headers are not required to be manually populated anymore.
  • vinay Wednesday, October 30, 2019
    Hi, I was able to do till step-5 and I could see that the jsrsasign is set, but when invoking the OCI rest apis, i'm getting the error "There was an error in evaluating the Pre-request Script: undefined: undefined". Also, how can we specify the pass phrase for the private key?
  • Imran Friday, December 13, 2019
    Excellent article Ashish.
    I am able to invoke OCI REST APIs in postman now.

    OCI should have kept this simple. Thanks to you, i have saved lot of time following this article.
  • Jose Hijar Wednesday, February 12, 2020
    Thanks Ashish! This information was very help ful for me.

    Just I have one comment:
    When I tested when a Private Key that requires a passphrase, the generated Authorization headers does not work to authenticate to OCI Endpoints/

    I was able to sorted out by adding a variable named "passphrase" to OCI_Environment collection and in OCI_REST_COLLECTION Pre-request script, retrieve the value of "passphrase" env var and pass it as parameter to init method of sign variable, only if the "passphrase" env var is present:

    var passphrase_var = pm.environment.get("passphrase");
    if(passphrase_var) {
    console.log("Using passphrase");
    } else {
    console.log("No passphrase");

    Thanks again!
  • Rajeev Akotkar Saturday, August 15, 2020
    I am able to do the set up steps smoothly but while I run the api the postman goes on infinite hang mode also I dont see the auth headers added to my request. I am using windows 10 , Postman native app version 7.30.1
  • sdds Saturday, August 15, 2020
    I was able to sorted out by adding a variable named "passphrase" to OCI_Environment collection and in OCI_REST_COLLECTION Pre-request script, retrieve the value of "passphrase" env var and pass it as parameter to init method of sign variable, only if the "passphrase" env var is present: https://www.google.com/
  • Greg E Wednesday, September 2, 2020
    One important thing I just found out using postman: I wasn't able to use environment variables inside of the content of my JSON payloads or on the URL strings. I think this is because the pre-request scripts happen before variable substitution.

    This meant that my content length and other values were slightly wrong, and i was getting authorization denied.

    So on your URLs and in your payloads, don't use environment variables.
  • Christoph Tuesday, September 15, 2020
    This worked for me. Can you please explain why only requests in the OCI_REST_COLLECTION work?
    When I create a request outside this collection, I receive an error.
  • Ashish Singh Tuesday, September 15, 2020
    Hi Jose,
    This has been fixed. Thanks.
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha