Call the Developer APIs with Authorization Code

Prerequisites to Complete

Before you can call the Oracle Integration Developer APIs with Authorization code, you must create a confidential client application and perform other prerequisites.

You must be the OCI tenant and domain administrator to configure the confidential client application and assign roles.

For instructions, see:
  1. Access the Identity Domain.
  2. Configure prerequisites for your grant type:

Information You Need

The following is information you need to send requests through a client.
Information You Need Where to Find It
Design-time URL or Runtime URL, depending on your use case See Do You Use the Design-time or Runtime URL?.

Example Design-time URL:

https://design-integration-region.ocp.oraclecloud.com/

Example Runtime URL:

https://myInstance-integration-region.ocp.oraclecloud.com/

Domain Host

You can get the identity domain host from the Domain URL field of the domain you are in. For instructions on accessing your domain, see Access the Identity Domain..

Default Domain page, accessed by selecting Identity, Domains, Default Domain, with the Domain URL field highlighted

Client ID

Client Secret

Add the client ID for the confidential application that you configured.

To find your confidential application, access the identity domain, select Integrated Applications, select your application, and look for OAuth Configuration, then Client ID and Client Secret. For instructions, see Access the Identity Domain.

Scope

Add the same scope that you added to your confidential application. You can find the scope you added to the confidential application in your confidential application details under Token Issuance Policy.

To find your confidential application, access the identity domain, select Integrated Applications, select your application, and look for OAuth Configuration, then Client ID and Client Secret. For instructions, see Access the Identity Domain.

This scope allows users to access both integration endpoints and Oracle Integration Developer APIs: 

https://69415C303.integration.ocp.oraclecloud.com:443urn:opc:resource:consumer::all

This scope allows users to only access the Oracle Integration Developer APIs: 

https://415C303.integration.ocp.oraclecloud.com:443/ic/api/

Integration Instance

Name of the integration instance.

Redirect URL

You can find the redirect URL in the Authorization area of the confidential client.

Configure Postman for Authorization Code

Postman Configuration page, with Authorization tab selected, fields from top to bottom are Grant Type, Callback URL, Auth URL, Access Token URL, Client ID, Client Secret, Scope
  1. Use the Design-time URL or Runtime URL depending on your use case. See Do You Use the Design-time or Runtime URL?.

    Example Design-time URL with a call to the Oracle Integration Developer API for connections: 

    https://design-integration-region.oraclecloud.com/ic/api/integration/v1/connections

    Example Runtime URL:

    https://myInstance-integration-region.oraclecloud.com/ic/api/integration/v1/connections

    Note:

    If you use the Runtime URL, you'll need to configure Postman to Follow Authorization Header in the request settings. This is because if you call the Oracle Integration Developer APIs with the Runtime URL, Oracle Integration redirects to the Design-time URL for the Developer APIs and the call will fail if the authorization header is missing from the request header.

    In cURL, use the -l option to forward the authorization header during the redirection.

    To configure Postman to forward the authorization header when using the Runtime URL:
    1. In the request, click Settings and enable Follow authorization header. Postman Settings tab selected with Follow authorization header highlighted to be set to ON.
  2. Fill in the required fields.
    Field What to enter

    Authorization type

    		 OAuth 2.0

    Grant Type

    		 Authorization Code
    Callback URL This is the Redirect URL you configured in the confidential client application. You can find the Redirect URL in the confidential client application under the Authorization section.
    Auth URL Use the identity domain host you identified from your domain URL to create the Auth URL. For example: https://<identity_domain_host>/oauth2/v1/authorize

    Access Token URL

    		 Use the identity domain host you identified from your Domain URL.

    For example: https://<identity_domain_host>/oauth2/v1/token

    Client ID

    Add the client ID for the confidential application that you configured.

    Client Secret

    Add the client secret for the confidential application that you configured.

    Scope

    Add the same scope that you added to your confidential application.

    Client Authentication

    		 You can choose anything here, does not apply.
  3. Click Get New Access Token.
  4. Click Use Token.

    Your token is attached to your request in the Header section.

  5. Click Send to make the call to the API. You should get a list of connections.

cURL command for Authorization Code

  1. From your browser, request an authorization code. For example:
    GET
      https://<identity_domain_host>/oauth2/v1/authorize?client_id=<clientID>&response_type=code&redirect_uri=https://app.getpostman.com/oauth2/callback&scope=https://<Resource_APP_Audience>urn:opc:resource:consumer::all%20offline_access&nonce=121&state=12345544

    Syntax:

    GET
      https://<identity_domain_host>.identity.oraclecloud.com/oauth2/v1/authorize?client_id=<client-id>&response_type=code&redirect_uri=<client-redirect-uri>&scope=<app_scope>%20offline_access&nonce=<nonce-value>&state=<unique_value>
    where:
    • <identity_domain_host> is the host name in the Domain URL field of the domain you are in.Default Domain page, accessed by selecting Identity, Domains, Default Domain, with the Domain URL field highlighted
    • <client-id> - ID of Client application generated

    • <client-redirect-uri> - Redirect URI, in client application. The Redirect URL needs to be accessed when you click on provide consent on the connection. This is the redirect URL of the Oracle Integration host. Format: https://<Service Console URL>/icsapis/agent/oauth/callback. This is the standard callback URL for the Oracle Integration instance.

    • <app scope> - Add the same scope that you added to your confidential application.

      This scope allows users to access both integration endpoints and Oracle Integration Developer APIs: 

      https://69415C303.integration.ocp.oraclecloud.com:443urn:opc:resource:consumer::all

      This scope allows users to only access the Oracle Integration Developer APIs: 

      https://415C303.integration.ocp.oraclecloud.com:443/ic/api/
    • nonce - Optional, unique value to mitigate replay attacks
    • state - Recommended, Opaque to IAM. Value used to maintain state between the request and the callback
  2. If the user is not already logged in, you are challenged to authenticate your user credentials.
    After authentication is successful, the client URL is redirected with the authorization code and state added to the URL.
    ##Response URL
https://<redirect_URL>?code=<code_value>=&state=<state_value>
 
###Client should validate state received is same as one sent in request.
  3. Capture the code value from the above response and make the request to get the access token. For example:
    curl -i -H 'Authorization: Basic MDMx..NGY1' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<identity_domain_host>/oauth2/v1/token -d 'grant_type=authorization_code&code=AQAg...3jKM4Gc=&redirect_uri=https://app.getpostman.com/oauth2/callback
    Syntax:
    curl -i -H 'Authorization: Basic <base64-clientid-secret>' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<identity_domain_host>.identity.oraclecloud.com/oauth2/v1/token -d 'grant_type=authorization_code&code=<authz-code>&redirect_uri=<client-redirect-uri>
    where:
    • <base64-clientid-secret> - BAse 64 encode clientId:ClientSecret
    • <authz-code> - code value received as response on redirect.
    • <client-redirect-uri> - Redirect URI, in client application.
  4. Capture the access_token and refresh_token from the response.
    {
    "access_token": "eyJ4NXQjG...dfsdfsFgets2ed",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "AQAgY2MzNjVlOTVhOTRh...vM5S0MkrFSpzc="
}
  5. Use the access_token in the authorization header to invoke the Oracle IntegrationDeveloper API.
    curl --location --request GET 'https://<OIC_host>/ic/api/integration/v1/connections' \
--header 'Authorization: Bearer eyJ4NXQjG...dfsdfsFgets2ed'

    • Where <oic_host> is the Design-time URL host name or Runtime URL host name. See Do You Use the Design-time or Runtime URL?.

      Note:

      If you use the Runtime URL host name, you'll need to use the -l option to forward the authorization header because you are automatically redirected to the Design-time host.

Update the Access Token

To update the access token, use the refresh token and make the request.
  1. Capture the access_token and refresh_token from a response for further use. For example:
    
curl -i -H 'Authorization: Basic OGQyM...ZDA0Mjcz' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<Identity_Domain_Host>.identity.oraclecloud.com/oauth2/v1/token  -d 'grant_type=refresh_token&refresh_token=AQAgY2MzNjVlOTVhOTRh...vM5S0MkrFSpzc='

    Syntax:

    curl -i -H 'Authorization: Basic <base64-clientid-secret>' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<Identity_Domain_Host>.identity.oraclecloud.com/oauth2/v1/token  -d 'grant_type=refresh_token&refresh_token=<refresh_token>'