1. REST API for Oracle Digital Assistant on Oracle Cloud Infrastructure REST API for Oracle Digital Assistant
  2. Send Requests
  3. Send IDCS OAuth Requests

Send IDCS OAuth Requests

With Digital Assistant instances that are paired with a subscription to a Fusion-based Oracle Cloud Applications service, such as HCM Cloud or Sales Cloud, and 19.4.1 instances that were migrated to Oracle Cloud Infrastructure, you use IDCS OAuth to authenticate your requests.

To ensure that your instance is enabled for OAuth, ask your service administrator to verify that your instance has an IDCS confidential application for the Digital Assistant UI, which will have a name that matches the first part of your Digital Assistant instance's fully-qualified domain name (FQDN). For example, if your instance's FQDN is idcs-oda-abcd1234-p0.digitalassistant.example.com, then your instance must have been provisioned with an application with the name idcs-oda-abcd1234-p0. See the steps below for how to access this application from the root compartment on the Digital Assistant Instances page.

Note:

If the Digital Assistant instance is in a tenant that was created for instances that were migrated from 19.4.1 environments, but the instance isn't one of the migrated instances, then it won't have the required IDCS confidential application, which means that you can't use OAuth on that instance.

To use OAuth, you must have permission to access the IDCS confidential application for the Digital Assistant UI.

Here's how to authenticate using OAuth.

Before You Begin:

Ask your company's Digital Assistant system administrator or IDCS identity domain administrator for the following information:

  • The IDCS OAuth token endpoint. See the steps below.

  • The client ID and secret for the IDCS confidential application that protects the Digital Assistance UI (botsui). See the steps below.

  • The OAuth scope, which is the same as the base URL for the Digital Assistant REST APIs. The OAuth scope is a concatenation of https://, the Digital Assistant instance's fully-qualified domain name, and /api/v1. For example, https://idcs-oda-abcd1234-p0.digitalassistant.example.com/api/v1.

    This is the only scope that's supported for the REST APIs.

Your administrator can get the OAuth token endpoint, client ID, and client secret by following these steps:

  1. Sign in to the Infrastructure console.

  2. To get the OAuth token endpoint, click the menu icon in the top-left corner to open the navigation menu, click Identity, and then click Federation. Click the name of the identity cloud service, and make a note of the fully-qualified domain name (FQDN) portion of the Oracle Identity Cloud Service Console URL.

    For example, if the Oracle Identity Cloud Service Console URL is https://idcs-12345.identity.oraclecloud.com/ui/v1/adminconsole/, then the FQDN is idcs-abc12345.identity.oraclecloud.com.

  3. To construct the OAuth token endpoint, concatenate https://, the FQDN, and /oauth2/v1/token. For example: https://idcs-abc12345.identity.oraclecloud.com/oauth2/v1/token.

  4. To get the client ID and client secret, click the menu icon in the top-left corner to open the navigation menu, and then click Digital Assistant.

  5. On the Digital Assistant Instances page, select the root compartment, then click the name of your Digital Assistant instance.

  6. Click the Tags tab, copy the idcsAppConsoleUrl, and then go to that URL in your browser.

  7. On the application page, click the Configuration tab.

  8. Expand General Information, and copy the values shown for the client ID and client secret.

To Use OAuth from a REST Client:

To use OAuth from a REST Client, you first send a request like the example below to get an access token, and then you use the access token in your Digital Assistant REST request, as described in the following steps. 

curl -i
-H "Authorization: Basic <base64-encoded[client-id:client-secret-string]>"
-H "Content-Type: application/x-www-form-urlencoded; charset=utf-8"
-d "grant_type=client_credentials&scope=<scope>"
--request POST <oauth-token-endpoint> 

  1. Base64 encode the clientID:clientSecret string, where clientId and clientSecret are the values for the IDCS application that protects the Digital Assistant UI (botsui).

  2. In the REST request to get the access token, which is shown in the example above, set the Authorization header to Basic <base64-encoded[client-id:client-secret-string]>. Replace <base64-encoded[client-id:client-secret-string]> with the value that you obtained in the previous step.

  3. Set the Content-Type to application/x-www-form-urlencoded; charset=utf-8.

  4. Set the request body to grant_type=client_credentials&scope=<scope>. Replace <scope> with the OAuth scope that was described in Before You Begin.

  5. Send the POST request to the OAuth token endpoint that you obtained from your administrator.

    The response includes an access_token property, as shown in this example (the value for access_token, which is a very long string, is truncated in this example). Copy this token for the next step. 

    { ...
  "access_token": "eyJ4NXQjUzI1NiI6Ijg1a...SsqtmgzK1dFs",
  ...
  "token_type": "Bearer", 
  ...
}

  6. When you send a request to the Digital Assistant REST API, set the Authorization header to Bearer <access-token>.

  7. Send the request using the Digital Assistant instance's fully-qualified domain name plus the base path /api/v1 plus the operation's path. For example, to send a request to get a list of digital assistants, send the request to https://idcs-oda-abcdefg1234.digitalassistant.example.com/api/v1/digitalAssistants