1. REST API for Oracle Cloud StackREST API for Oracle Cloud Stack Manager
  2. Authentication

Authentication

In order to use the Oracle Cloud Stack REST API you must provide valid Oracle Cloud credentials along with an identity domain.

You must have a valid Oracle Cloud account with subscriptions to the cloud services that you plan to provision as part of your cloud stacks. For example, if your cloud stack creates a storage container in Oracle Storage Cloud Service as well as an instance of Oracle Java Cloud Service, the account credentials you use with Oracle Cloud Stack must have rights to both Oracle Storage Cloud Service and Oracle Java Cloud Service. However, you do not have to explicitly request or purchase a subscription to Oracle Cloud Stack itself in order to use it.

You provide credentials to the REST endpoints as HTTP request headers, and access the REST endpoints over HTTPS to ensure that these credentials are not visible to third parties. Specifically you must provide this information:

  • An SSL certificate authority (CA) certificate file or bundle to authenticate against the Verisign certificate authority (CA) certificate. Oracle Cloud uses a CA certificate issued by Verisign to enable clients to connect securely to the server.

  • The standard Authorization header, which specifies the Oracle Cloud user name and password. The user name and password are separated by a colon and encoded using Base64 encoding.

  • A custom header, X-ID-TENANT-NAME, that identifies the Oracle Cloud identity domain for this user. This identity domain is typically also part of the endpoint URL.

For example, to authenticate using the cURL tool:

  • Use the -u option to set the user name and password, which cURL uses to create the Authorization header.

  • Use the -H option to set the X-ID-TENANT-NAME custom header.

  • When running cURL from a Windows command shell only, set the cURL environment variable, CURL_CA_BUNDLE, to the location of an SSL certificate authority (CA) certificate file or bundle to authenticate against the Verisign CA certificate. Alternatively, you can specify the location of your local CA certificate bundle on the command line, using the --cacert command line option.

    You can download an SSL CA certificate bundle from http://curl.haxx.se/docs/caextract.html or provide your own. For information about CA certificate verification using cURL, see: http://curl.haxx.se/docs/sslcerts.html.

The following cURL command example retrieves the details of the MyStack cloud stack: 

curl -i -X GET \
-u yourUsername:yourPassword \
-H "X-ID-TENANT-NAME:ExampleIdentityDomain" \
https://psm.us.oraclecloud.com/paas/api/v1.1/instancemgmt/ExampleIdentityDomain/services/stack/instances/MyStack

Note: On accounts that are integrated with Oracle Identity Cloud Service, you must use the Identity Cloud Service tenant name in the REST endpoints. This tenant name begins with the characters idcs- and is followed by a string of number and letters (for example, idcs-98888f7964454b658ac6d2f625b29030). See Find Your Oracle Identity Cloud Service Tenant Name in Administering Oracle Identity Cloud Service.

Note: All of the examples in this guide use the URL prefix and context path for the United States region in Oracle Cloud. For information about the context path and the URL prefixes for other regions of the world, see Send Requests.