1. OKCS REST APIREST API for Knowledge Advanced in B2C Service
  2. Learn More
  3. Authenticate and Authorize

Authenticate and Authorize

This topic describes how you can access the Oracle B2C Service Knowledge Advanced REST APIs by performing the following tasks:

  1. Creating the Users to Access the APIs
    1. Creating the API User
      1. Creating the API Role
      2. Creating an API User Using Information Management Console
    2. Creating the Console User
    3. Creating the Web User
  2. Authenticating and Authorizing the Users to Ensure Access to the APIs
    1. Authenticating and Authorizing the API User
    2. Authenticating and Authorizing the Console User
    3. Authenticating and Authorizing the Web User
    4. Authenticating and Authorizing the Staff Account or the Contact User using OAuth 2.0
  3. Accessing the REST API
    1. Accessing the REST API Anonymously
    2. Accessing the REST API with a Console User
    3. Accessing the REST API with a Web User

Creating the Users to Access the APIs

You need to have at least an API User to access the REST APIs. A Web user or Console user can be used along with the API User to access the REST APIs.

The following topics explain how to create an API User, the Console User, and the Web User.

Creating the API User

Creating the API user involves two steps: Creating the API Role and Creating an API User Using Information Management Console

Creating the API Role

Perform the following steps to create the API Role.

  1. Access the Information Management Console.
  2. Click the Users tab. The following figure shows the Users tab.The figure shows how the Users tab appears in an Information Management console.
  3. Click Add under API Roles. The API Role Properties page appears.The figure displays the Role Information and REST API Access sections of the API Role Properties page. The Role Information section contains Role Name and Reference Key fields. The REST API Access section contains a list of all the available endpoints.
  4. Enter the role information details.
  5. Select the REST API check boxes to indicate the areas of the API that you want to assign to the role.
  6. Click Save Role Properties

Creating an API User Using Information Management Console

Perform the following steps to create an API User

  1. Access the Information Management Console.
  2. Click the Users tab. The following figure shows the Users tab.The figure displays the Role Information and REST API Access sections of the API Role Properties page. The Role Information section contains Role Name and Reference Key fields. The REST API Access section contains a list of all the available endpoints.
  3. Click Add under API Users. The API User Properties page appears.The figure shows different sections of an API User Properties page. The API User Properties page contains Account Information, Account Status, and Security Roles sections. The Account Information section lists various properties of an user, such as first name, last name, user ID, and so on.
  4. Enter the API User information.

    Note:

    The password lifecycle is not applicable for the API Users. The password must be between 6 and 20 characters, and should not be same as the last used password.
  5. Select the API Security Role(s) that you want to assign to the user.
  6. Click Save User Properties.

Creating the Console User

In Oracle B2C Service Knowledge Advanced, to create a Console User, you will need to create an Account User using the Agent Desktop. When you make an Account User in the Agent Desktop, a corresponding Console user is created. The system creates the corresponding Console User when you access the Knowledge Authoring pages within the Agent Desktop or upon the access of the REST APIs using the newly created Account User.

Perform the following steps to create a Console User.

  1. Log in to the Agent Desktop.
  2. Click Staff Accounts by Profile under the Staff Management menu on the Navigation pane. The Staff Accounts by Profile page appears. The following figure shows the Staff Accounts by Profile page which lists the accounts available.The figure shows how a list of available accounts appear in a Staff Accounts by Profile page.
  3. Click the New button on the menu bar. The Account Details - Edit page appears. The following figure shows the Account Details - Edit page.The figure shows how the list of account details of a Console User appear in the Account Details Edit page. The Account Details Edit page allows you to modify the login details such as user name, password and various other settings such as first name, last name, and display name of a Console User.
  4. Enter the account details.
  5. Click the Save and Close button in the menu bar.

Creating the Web User

In Oracle B2C Service Knowledge Advanced, to create a Web User, you will need to create a Contact User using the Agent Desktop or Customer Portal. You can log-in to the Agent Desktop as an Account user and then create a Contact User or you can register a new Contact User using Customer Portal. The system creates the corresponding Web User when you access the REST API or log-in to Customer Portal using the newly created Contact User.

Perform the following steps to create a Web User.

  1. Access Customer Portal.
  2. Click Log in or Sign Up. The Create an Account page appears. The following figure shows the Create an Account page.The figure shows how a Create an Account page appears from an Agent Desktop or Customer Portal. The page contains the list of account details, such as email address, user name, display name and so on, which you need to specify to create a web user.
  3. Enter the account details and click Create an Account.

Authenticating and Authorizing the Users to Ensure Access to the APIs

This section discusses how you can generate authorization tokens for an API, Console, and Web user. You need to authenticate and authorize the user to get authorization tokens which you will need to access the APIs.

Authenticating and Authorizing the API User

To authenticate and authorize the API User, you must send a POST request using the URI /km/api/latest/auth/integration/authorize.

Enter the following details as the kmauthtoken header value:

  • siteName: The name of the site from where you are trying to access the APIs.
  • localeId: The localeId of the Locale you are trying to access the APIs with. E.g. en_US for English United States.

You must also provide the payload containing the RequestIntegrationAuth object to supply the API User's credentials. You can provide the payload with the Accept header value asapplication/json andapplication/xml.

The following set of codes shows an example of the request payload in the JSON format.

HTTP REQUEST

POST
/km/api/latest/auth/integration/authorize HTTP/1.1

Request Header

Content-type: application/json 
Accept: application/json
kmauthtoken: {"siteName":"ORACLE_KNOWLEDGE","localeId":"en_US"}

Request Payload

{"login":"test123","password":"Test123","siteName":"ORACLE_KNOWLEDGE"}

The response payload includes the authentication token when the user is successfully authenticated.

The request returns an error if the authentication is unsuccessful.

The following figure shows an example of the authentication token.

Server Response(HTTP/1.1 200 OK)

authenticationToken: "+eCJYkxKwj5HUaIiJYun0/TpatwT1LmtcsF05W33xnEojifV/AsLDj9RpN0lKuorTMNKeSE1tgC7svVL+BzntqDON4KiM1HFlpxvXEUCB0P2w0Xrs75McygqxdVaDSE9"

Authenticating and Authorizing the Console User

To authenticate and authorize the Console User, you must send a POST request using the URI/km/api/latest/auth/authorize.

Enter the following details as the kmauthtoken header value:

  • siteName: The name of the site from where you are trying to access the APIs.
  • localeId: The localeId of the Locale you are trying to access the APIs with. E.g. en_US for English United States.
  • integrationUserToken: The authentication token value given for the desired API User.

You must also provide the payload containing the form data to supply the Console User's credentials.

The form data must include the following credentials:

  • userName: The Console User's username.

  • password: The Console User's password.

  • siteName: The name of the site from where you are trying to access the APIs.

  • userExternalType: The value must be set to ACCOUNT for Console Users.

In Oracle B2C Service Knowledge Advanced, an Account and a Contact can have the same username. When you use an Account User that has the same username as a Contact User to authenticate the Web User, the system authenticates the Console User that corresponds to the specified Account User.

Note:

The system always authenticates against the Account User's corresponding Console User when an Account User and Contact User share the same username (even when authenticating a Contact).

The following figure shows an example of the authentication request for the Console User.

HTTP Request

POST
/km/api/latest/auth/authorize HTTP/1.1

Request Headers

Content-type: application/json 
Accept: application/json
kmauthtoken: {"siteName":"ORACLE_KNOWLEDGE","localeId":"en_US", "integrationUserToken":"+eCJYkxKwj5HUaIiJYun0/TpatwT1LmtcsF05W33xnEojifV/AsLDj9RpN0lKuorTMNKeSE1tgC7svVL+BzntqDON4KiM1HFlpxvXEUCB0P2w0Xrs75McygqxdVaDSE9"}

Form Data

userName:okcsuser
password:Password1
siteName:ORACLE_KNOWLEDGE
userExternalType:ACCOUNT

The response payload includes the authentication token when the user is successfully authenticated.

The request returns an error if the authentication is unsuccessful.

The figure below shows an example of the authentication token.

Server Response (HTTP/1.1 200 OK)

authenticationToken:"{"localeId":"en_US","knowledgeInteractionId":null,"billableSessionId":null,"appId":null, "siteName":"ORACLE_KNOWLEDGE","interfaceId":null,"requiresBillable":null,"captureAnalytics":null,"integrationUserToken":null, "userToken":"+lOR60Szzpk+3aiBn2uJ3BSqBrT79DaIVoC8zb6OVofvC37kOjp0/Wk7G7zOpOj0vMHxi/3FQafXP3UIon7so6lM+ALQOflDpEmGyk2qvz2QFLMZxdbSatwsQ1vz6A2i/OyfUhb9dxw==", "referrer":null,"querySource":null}"

Authenticating and Authorizing the Web User

To authenticate and authorize the Web User, you must send a POST request using the URI/km/api/latest/auth/authorize.

Enter the following details as the kmauthtoken header value:

  • siteName: The name of the site from where you are trying to access the APIs.

  • localeId: The localeId of the Locale you are trying to access the APIs with. E.g. en_US for English United States.

  • integrationUserToken:The authentication token value given for the desired API User.

You must also provide the payload containing the form data to supply the Web User's credentials.

The form data must include the following credentials:

  • userName: The Web User's user name.

  • password: The Web User's password.

  • siteName: The name of the site from where you are trying to access the APIs.

  • userExternalType: The value must be set to CONTACT for Web Users.

In Oracle B2C Service Knowledge Advanced, an Account and a Contact can have the same username. When you use a Contact User that has the same username as an Account User to authenticate the Web User, the system authenticates the Console User that corresponds to the specified Account User.

Note:

The system always authenticates against the Account User's corresponding Console User when an Account User and Contact User share the same username (even when authenticating a Contact).

The following figure shows an example of the authentication request for the Web User.

HTTP Request

POST
/km/api/latest/auth/authorize HTTP/1.1

Request Headers

Content-type: application/json Accept: application/json  kmauthtoken: {"siteName":"ORACLE_KNOWLEDGE","localeId":"en_US", "integrationUserToken":"+eCJYkxKwj5HUaIiJYun0/TpatwT1LmtcsF05W33xnEojifV/AsLDj9RpN0lKuorTMNKeSE1tgC7svVL+BzntqDON4KiM1HFlpxvXEUCB0P2w0Xrs75McygqxdVaDSE9"}

Form Data

userName:webuser
password:Password1
siteName:ORACLE_KNOWLEDGE
userExternalType:CONTACT

The response payload includes the authentication token when the user is successfully authenticated.

The request returns an error if the authentication is unsuccessful.

The figure below shows an example of the authentication token.

Server Response (HTTP/1.1 200 OK)

authenticationToken:"{"localeId":"en_US","knowledgeInteractionId":null,"billableSessionId":null,"appId":null, "siteName":"ORACLE_KNOWLEDGE","interfaceId":null,"requiresBillable":null,"captureAnalytics":null,"integrationUserToken":null, "userToken":"bOOq20Tu+MWcEBLH0JTNHnt+eqElIvX3hO+I6zUZui6zJW4La0J9rwtirqdiPYbgDSxyOGl70tAaNq2jev9EsvE9A98EI0bDuRWKOPVc/RyzGTna/pxusLr/lVg2ZM0r", "referrer":null,"querySource":null}"

Authenticating and Authorizing the Staff Account or the Contact User using OAuth 2.0

If you are a staff account, from August 2018, you can use either OAuth 2.0 authorization framework or the regular authorization mechanism for accessing Oracle B2C Service Knowledge Advanced REST APIs. If you are a contact user, from May 2019, you can use either OAuth 2.0 authorization framework or the regular authorization mechanism for accessing Oracle B2C Service Knowledge Advanced REST APIs.

Before you use OAuth 2.0 authorization framework, ensure that your application is configured to get OAuth tokens from Oracle Identity Cloud Service or an external identity provider. You must also ensure that IDCS OAuth support is enabled in Knowledge Advanced. For more information, see Configure OAuth Support for the REST APIs .

Note:

Use of OAuth 2.0 framework for authorization is supported only for staff accounts and contact users.
  1. Send a POST request for authentication as shown in the following example.

    HTTP Request

    POST
    /km/api/latest/auth/integration/authorize HTTP/1.1

    Request Headers

    Content-type: application/json
    Accept: application/json
    kmauthtoken: {"siteName":" im_rest_api_site ","localeId":"en_US"}

    Request Payload

    {"login":"User123","password":"Password","siteName":"im_rest_api_site"}

    A custom token called authenticationToken is returned after authentication is successful.

    Response

    { "authenticationToken": 
"+eCJYkxKwj5HUaIiJYun0/TpatwT1LmtcsF05W33xnEojifV/AsLDj9RpN0lKuorTMNKeSE1tgC7svVL+BzntqDON4KiM1HFlpxvXEUCB0P2w0Xrs75McygqxdVaDSE9" }
  2. Request an OAuth token value from your Oracle Identity Cloud Service server or an external identity provider in JWT format. For more information on how to request an OAuth token using Oracle Identity Cloud Service, see Working with OAuth 2 to Access the REST API. For more information on JSON Web Token, see Use JSON Web Token for Authorization.

    Note:

    The OAuth token expires after a specified time period based on the configuration of Oracle Identity Cloud Service or the external identity provider. Whenever your OAuth token expires, you need to request a new OAuth token.
  3. Send a sample GET request with the integrationUsertoken and OAuth token as shown in the following example.

    As shown, you must specify an Authorization header with the OAuth token value instead of including a user token for authorization.

    HTTP Request

    GET
    /km/api/latest/content?limit=10&q=publishDate+after+%272014-04-01%27&orderBy=mostPopular&mode=key HTTP/1.1

    Request Headers

    Content-type: application/json
    Accept: application/json
    Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cC...SKIP...-bqMwJGDT-A
    kmauthtoken: {"localeId":"en_US","siteName":"im_rest_api_site", "integrationUserToken":"+eCJYkxKwj5HUaIiJYun0/TpatwT1LmtcsF05W33xnEojifV/AsLDj9RpN0lKuorTMNKeSE1tgC7svVL+BzntqDON4KiM1HFlpxvXEUCB0P2w0Xrs75McygqxdVaDSE9"}

    The preceding request returns the most popular documents published after 01-Jan-2014 in Oracle Knowledge repository.

    Response

    {
"recordId": "048016517ab56ef014519740375005599",
"versionId": "048016517ab56ef01451974037500544f",
"documentId": "OR4",
"title": "Registration Now Open to the Public for Oracle OpenWorld San Francisco 2014",
"version": "2.0",
"answerId": 1000077,
"links": [
{
"rel": "canonical",
"href": "http://localhost:7002/km/api/latest/content/048016517ab56ef014519740375005599",
"mediaType": "application/json, application/xml",
"method": "GET"
},
{
"rel": "collection",
"href": "http://localhost:7002/km/api/latest/content",
"mediaType": "application/json, application/xml",
"method": "GET",
"profile": "http://localhost:7002/km/api/latest/metadata-catalog/content"
}
]
}

Accessing the REST API

You can access the APIs anonymously, as a Console User, or as a Web User.

Note:

You can only access the APIs that are allowed for your API User's Security Role(s). You get an authorization error if the API User's Security Role(s) do not have access to the requested API.

To gain access to the REST APIs, you need to provide the API Session Token in the kmauthtoken header. The API Session Token must contain the siteName, the localeId and the Integration User Token (integrationUserToken). The integrationUserToken is required for all REST API requests except for an API User authorization request (POST /km/api/auth/integration/authorize).

For analytics and billing purposes, get a knowledge interaction ID using the Content (IM)/Knowledge Interaction/Start interaction API. Then, specify both knowledge interaction ID and interaction ID generated parameters in the kmauthtoken header in all subsequent requests. For more information about knowledge interaction ID, see Content (IM)/Knowledge Interaction/Start interaction.

Note:

The authentication token for a given API User expires in one day. To regain access to the REST APIs after the expiration of the token, you need to make another API User authorization request and update the API Session Token with the new integrationUserToken value.

Accessing the REST API Anonymously

To access the REST APIs anonymously, set the following details as the value of the API Session Token.

  • siteName: The name of the site from where you are trying to access the APIs.

  • localeId: The localeId of the Locale you are trying to access the APIs with. E.g. en_US for English United States.

  • integrationUserToken: The authentication token value given for the desired API User.

  • interactionIdGenerated: (optional) After a knowledgeInteractionID is generated using the Start interaction API, you must set the value of interactionIdGenerated parameter as 'true' to enable user tracking and perform knowledgeInteractionID validation.

  • knowledgeInteractionId: (optional) The system generated unique session identifier for a user.

    Note:

    Analytics does not track events if you pass more than 64 characters in the knowledgeInteractionID attribute for Search or Article view APIs.

Note:

Some APIs are accessible only if you are an authenticated end user (a Console or Web User). You may get an authentication error if the request requires an authenticated end user.

The following figure shows an example request using the anonymous end user to get the most popular documents published after 01-Jan-2014 using the Content API.

HTTP Request

GET
/km/api/latest/content?limit=10&q=publishDate+after+%272014-04-01%27&orderBy=mostPopular&mode=key HTTP/1.1

Request Headers

Content-type: application/json Accept: application/json  kmauthtoken: {"localeId":"en_US","siteName":"ORACLE_KNOWLEDGE","interactionIdGenerated":"true","knowledgeInteractionId":"Z9X3D85Ka8C","integrationUserToken":"+eCJYkxKwj5HUaIiJYun0/TpatwT1LmtcsF05W33xnEojifV/AsLDj9RpN0lKuorTMNKeSE1tgC7svVL+BzntqDON4KiM1HFlpxvXEUCB0P2w0Xrs75McygqxdVaDSE9", "userToken":null}

The request returns the appropriate response only if the requested APIs are allowed to be accessed anonymously.

The following figure shows the response to the previous example.

Server Response (HTTP/1.1 200 OK)

{
"recordId": "048016517ab56ef014519740375005599",
"versionId": "048016517ab56ef01451974037500544f",
"documentId": "OR4",
"title": "Registration Now Open to the Public for Oracle OpenWorld San Francisco 2014",
"version": "2.0",
"answerId": 1000077,
"links": [
{
"rel": "canonical",
"href": "http://localhost:7002/km/api/latest/content/048016517ab56ef014519740375005599",
"mediaType": "application/json, application/xml",
"method": "GET"
},
{
"rel": "collection",
"href": "http://localhost:7002/km/api/latest/content",
"mediaType": "application/json, application/xml",
"method": "GET",
"profile": "http://localhost:7002/km/api/latest/metadata-catalog/content"
}
]
}

The request returns an error if the requested API is not allowed to be accessed anonymously or if the API Session Token is expired.

Accessing the REST API with a Console User

To access the REST APIs using a Console User as the end user, set the following details as the value of the API Session Token.

  • siteName: The name of the site from where you are trying to access the APIs.

  • localeId: The localeId of the Locale you are trying to access the APIs with. E.g. en_US for English United States.

  • integrationUserToken: The authentication token value given for the desired API User.

  • userToken: The authentication token value given for the desired Console User.

  • interactionIdGenerated: (optional) After a knowledgeInteractionID is generated using the Start interaction API, you must set the value of interactionIdGenerated parameter as 'true' to enable user tracking and perform knowledgeInteractionID validation.

  • knowledgeInteractionId: (optional) The system generated unique session identifier for a user.

    Note:

    Analytics does not track events if you pass more than 64 characters in the knowledgeInteractionID attribute for Search or Article view APIs.

Note:

The authentication token for a given Console User expires in one day. To regain access to the REST APIs after the expiration of the token, you need to make another Console User authorization request and update the API Session Token with the new userToken value.

The following figure shows an example request using the Console User as the end user to get the most popular documents published after 01-Jan-2014 using the Content API.

HTTP Request

GET
/km/api/latest/content?limit=10&q=publishDate+after+%272014-04-01%27&orderBy=mostPopular&mode=key HTTP/1.1

Request Headers

Content-type: application/json Accept: application/json  kmauthtoken: {"localeId":"en_US","siteName":"ORACLE_KNOWLEDGE","interactionIdGenerated":"true","knowledgeInteractionId":"Z9X3D85Ka8C","integrationUserToken":"+eCJYkxKwj5HUaIiJYun0/TpatwT1LmtcsF05W33xnEojifV/AsLDj9RpN0lKuorTMNKeSE1tgC7svVL+BzntqDON4KiM1HFlpxvXEUCB0P2w0Xrs75McygqxdVaDSE9","userToken":"+lOR60Szzpk+3aiBn2uJ3BSqBrT79DaIVoC8zb6OVofvC37kOjp0/Wk7G7zOpOj0vMHxi/3FQafXP3UIon7so6lM+ALQOflDpEmGyk2qvz2QFLMZxdbSatwsQ1vz6A2i/OyfUhb9dxw=="}

The request returns the appropriate response only if the requested APIs are allowed to be accessed by the Console User.

The following figure shows the response to the previous example.

Server Response (HTTP/1.1 200 OK)

{
"recordId": "048016517ab56ef014519740375005599",
"versionId": "048016517ab56ef01451974037500544f",
"documentId": "OR4",
"title": "Registration Now Open to the Public for Oracle OpenWorld San Francisco 2014",
"version": "2.0",
"answerId": 1000077,
"links": [
{
"rel": "canonical",
"href": "http://localhost:7002/km/api/latest/content/048016517ab56ef014519740375005599",
"mediaType": "application/json, application/xml",
"method": "GET"
},
{
"rel": "collection",
"href": "http://localhost:7002/km/api/latest/content",
"mediaType": "application/json, application/xml",
"method": "GET",
"profile": "http://localhost:7002/km/api/latest/metadata-catalog/content"
}
]
}

The request returns an error if the requested API is not allowed to be accessed by the Console User or if the API Session Token is expired.

Accessing the REST API with a Web User

To access the REST APIs using a Web User as the end user, set the following details as the value of the API Session Token.

  • siteName: The name of the site from where you are trying to access the APIs.

  • localeId: The localeId of the Locale you are trying to access the APIs with. E.g. en_US for English United States.

  • integrationUserToken: The authentication token value given for the desired API User.

  • userToken: The authentication token value given for the desired Web User.

  • interactionIdGenerated: After a knowledgeInteractionID is generated using the Start interaction API, you must set the value of interactionIdGenerated parameter as 'true' to enable user tracking and perform knowledgeInteractionID validation.

  • knowledgeInteractionId: (optional) The system generated unique session identifier for a user.

    Note:

    Analytics does not track events if you pass more than 64 characters in the knowledgeInteractionID attribute for Search or Article view APIs.

Note:

The authentication token for a given Web User expires in one day. To regain access to the REST APIs after the expiration of the token, you need to make another Web User authorization request and update the API Session Token with the new userToken value..

The following figure shows an example request using the Web User as the end user to get the most popular documents published after 01-Jan-2014 using the Content API.

HTTP Request

GET
/km/api/latest/content?limit=10&q=publishDate+after+%272014-04-01%27&orderBy=mostPopular&mode=key HTTP/1.1

Request Headers

Content-type: application/json Accept: application/json  kmauthtoken: {"localeId":"en_US","siteName":"ORACLE_KNOWLEDGE","interactionIdGenerated":"true","knowledgeInteractionId":"Z9X3D85Ka8C","integrationUserToken":"+eCJYkxKwj5HUaIiJYun0/TpatwT1LmtcsF05W33xnEojifV/AsLDj9RpN0lKuorTMNKeSE1tgC7svVL+BzntqDON4KiM1HFlpxvXEUCB0P2w0Xrs75McygqxdVaDSE9","userToken":"bOOq20Tu+MWcEBLH0JTNHnt+eqElIvX3hO+I6zUZui6zJW4La0J9rwtirqdiPYbgDSxyOGl70tAaNq2jev9EsvE9A98EI0bDuRWKOPVc/RyzGTna/pxusLr/lVg2ZM0r"}

The request returns the appropriate response only if the requested APIs are allowed to be accessed by the Web User.

The following figure shows the response to the previous example.

Server Response (HTTP/1.1 200 OK)

{
"recordId": "048016517ab56ef014519740375005599",
"versionId": "048016517ab56ef01451974037500544f",
"documentId": "OR4",
"title": "Registration Now Open to the Public for Oracle OpenWorld San Francisco 2014",
"version": "2.0",
"answerId": 1000077,
"links": [
{
"rel": "canonical",
"href": "http://localhost:7002/km/api/latest/content/048016517ab56ef014519740375005599",
"mediaType": "application/json, application/xml",
"method": "GET"
},
{
"rel": "collection",
"href": "http://localhost:7002/km/api/latest/content",
"mediaType": "application/json, application/xml",
"method": "GET",
"profile": "http://localhost:7002/km/api/latest/metadata-catalog/content"
}
]
}

The request returns an error if the requested API is not allowed to be accessed by the Web User or if the API Session Token is expired.