REST API for the Management Service in Oracle API Platform Cloud Service

Security, Authentication, and Authorization

When you send requests to Management Service REST endpoints in Oracle API Platform Cloud Service, you ensure secure, authenticated, and authorized access by providing the following 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 Authorization standard header to specify an access token issued for an Oracle API Platform Cloud Service user with authorization to perform the operation.

The Authorization Header

When making a request to Management Service REST endpoints in Oracle API Platform Cloud Service, you must specify an Authorization header whose value contains an access token issued by Oracle Identity Cloud Service for a specific user for the resource application associated with the Oracle API Platform Cloud Service instance. The header has the form:

Authorization: Bearer access_token

For example:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX3R6IjoiQW1lcmljYS9DaGljYWdvIiwic3ViIjoiW1wbGUiLCJ0ZW5hbnQiOiJzYW1wbGUiLCJqdGkiOiJzYW1wbGUifQ

When a request with an access token is received, the token is introspected to ensure the user for whom it is issued is valid and has the proper access to perform the requested operation. An error is returned if the token is not valid or the user does not have proper authorization to perform the operation.

Note:

In releases prior to 18.2.5, the REST endpoints were protected using Basic Authorization instead of OAuth. If you are using an earlier version, you must specify an Authorization header whose value contains the base 64-encrypted user name and password (separated by a colon) of an Oracle API Platform Cloud Service user with authorization to perform the requested operation. This header looks like:

Authorization: Basic base64-encrypted-username:base64-encrypted-password

Getting an Access Token

Users are issued tokens to the resource application from the Oracle Identity Cloud Service console or using the Oracle Identity Cloud REST API.

Note:

Not all users may be able to access the Oracle Identity Cloud Service console.

Generate an access token from the Oracle Identity Cloud Service console: See Generating Tokens for Trusted Applications in Administering Oracle Identity Cloud Service.

You must generate the token for the application associated with your Oracle API Platform Cloud Service instance. When generating the token, use the following options:

Option	Description
Available Scopes	Use the Customized Scopesoption.
Customized Scopes	Use the Invokes Other APIs option, and then select the application and scope that correspond to the resource application associated with your Oracle API Platform Cloud Service instance. The scope looks like this: `https://<app-id-in-identity-cloud-service>.<tenant-base-URL>:443.apiplatform`
Include Refresh Token	Do not select this option.

After generating the token, download and open the .tok file. The access token is the value of the app_access_token attribute.

You can find the app ID, client ID, client secret, and scopes for the resource application associated with your Oracle API Platform Cloud Service instance in the Oracle Identity Cloud Service console. See Viewing High-Level Information for Oracle Applications in Administering Oracle Identity Cloud Service.

Generate an Access Token using the Oracle Identity Cloud Service REST API: See Generate Access Token and Other OAuth Runtime Tokens to Access the Resource in REST API for Oracle Identity Cloud Service.

The Gateway Controller REST endpoints are protected using resource owner password credentials flow. When sending your request to Oracle Identity Cloud Service to get a token, you must use the password grant type. You must also provide your username, password, and the scope with the request, as shown in this example:
```
curl -i
-H 'Authorization: Basic <base64Encoded clientid:secret>'
-H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' 
--request POST https://<tenant-base-url>/oauth2/v1/token 
-d 'grant_type=password&username=<user-name>&password=<password>&scope=<scope>'
```
Where:
- <user-name> is your user name
- <password> is your password
- <scope> is the scope for the Oracle API Platform Cloud Service product REST APIs. The scope looks like this: https://<app-id-in-identity-cloud-service>.<tenant-base-URL>:443.apiplatform
To get the app ID, either ask your instance administrator or see Search Apps in REST API for Oracle Identity Cloud Service.

Once you have the app ID, you can use another API to get the scope value. See Get an App in REST API for Oracle Identity Cloud Service. The scope for your application is returned as the value of the fqs attribute.