Integrate Trusted Answer Search with Applications

Applications can call Trusted Answer Search through REST APIs or the DBMS_TRUSTED_SEARCH.SEARCH PL/SQL procedure. Both return ranked search targets and resolved target inputs.

Application access	Integration method
An HTTP client in your application or service	REST API
A connection to the Trusted Answer Search database	PL/SQL API

REST APIs

The REST APIs accept HTTP requests through Oracle REST Data Services (ORDS).

Obtain the installed ORDS base URL and the search space name. The search space must have a published version. Obtain an access token if authentication is required. Your application must be able to reach the endpoints. The caller must have access to the search space.

The endpoints are under <ORDS_BASE_URL>/trusted-search/search-api/. The base URL includes /ords and any database-specific path. Each endpoint path already includes the trusted-search schema alias. Do not add this alias to <ORDS_BASE_URL>.

JWT stands for JSON Web Token. It is a signed token that the application sends with an API request to identify the signed-in user. The service checks the token before allowing access.

When JWT authentication is enabled, send Authorization: Bearer <ACCESS_TOKEN> with each request. Use the signed-in user’s access token. If JWT is disabled and no user is identified, requests run anonymously. Anonymous users can search only public, published search spaces.

search/

Search the published version of a search space and return ranked results. The query and results are saved for review in the Admin application.

GET <ORDS_BASE_URL>/trusted-search/search-api/search/

Request headers

`X-Q`

string · Required

The text to search for. It must not be blank or a vector-like value such as [1,2,3]. Maximum length: 2,000 characters. If word replacements are configured, this limit applies after those replacements.

`X-N`

string · Required

Search space name, such as wikimedia. Maximum length: 100 characters. The space must have a published version.

`Authorization`

string · Required when JWT authentication is enabled

Bearer <ACCESS_TOKEN> for the signed-in user.

The X-Q request header contains the search query. The X-N request header contains the search space name. Both endpoints search the published version of the search space.

Returns

A JSON object with content type application/json.

`search_id`

string · Always returned

Identifier of the saved search.

`search_matches`

array of objects · Always returned

Ranked search targets. An empty array means no targets matched.

Child fields

`rank`

integer · Always returned

Result position, starting at 1. Use this field to order results.

`search_target_id`

string · Always returned

Identifier of the matched search target.

`search_target_title`

string · Always returned

Search target title to display.

`score`

number · Always returned

Ranking score, rounded to five decimal places. When hybrid search is enabled, keyword and semantic results contribute to the ranking. With hybrid search disabled, ranking uses keyword-only matching.

`url`

string · URL target only

Configured URL template. It can contain unresolved input names.

`sql`

string · SQL target only

Configured SQL template before input values are inserted. Bind the input values separately when executing this template.

`resolved_target_action`

string or null · Always returned

For a URL target, the URL to open when the user selects the result. For a SQL target, a preview of the SQL statement. Null when no action is available.

`resolved_target_action_type`

string or null · Always returned

URL, SQL, or null when no action is available.

`target_input_matches`

object · Always returned

Target input names and their resolved values. Each value is a string or null. For example, "language": "it" means the language input resolved to Italian. The object is empty when no input values are available.

Example request

This example uses the Wikimedia search space. Replace <ORDS_BASE_URL> with your database’s ORDS base URL, such as https://<host>/ords. Include any database-specific path. Replace <ACCESS_TOKEN> with the user’s access token. The endpoint path already includes the trusted-search schema alias. Omit the Authorization header only if anonymous access is allowed.

curl --request GET \
  --header "Authorization: Bearer <ACCESS_TOKEN>" \
  --header "X-Q: italian page views" \
  --header "X-N: wikimedia" \
  "<ORDS_BASE_URL>/trusted-search/search-api/search/"

Example response

This example shows five Wikimedia matches. ... indicates omitted fields. The values are illustrative. Your results depend on the published search space and its configuration.

{
  "search_id": "432d0380-555e-4f7f-bf05-f15d61802b4e",
  "search_matches": [
    {
      "rank": 1,
      "search_target_id": "bd50fd19-14d7-4fd1-bf51-2f92c3becc50",
      "search_target_title": "Total Page Views",
      ...
      "score": 0.03227,
      "url": "https://stats.wikimedia.org/#/language.project.org/reading/total-page-views/normal|bar|period|~total|frequency",
      "resolved_target_action": "https://stats.wikimedia.org/#/it.wikipedia.org/reading/total-page-views/normal|bar|2-year|~total|monthly",
      "resolved_target_action_type": "URL",
      "target_input_matches": {
        "language": "it",
        "project": "wikipedia",
        "period": "2-year",
        "frequency": "monthly"
      }
    },
    {
      "rank": 2,
      "search_target_id": "2afc32e3-83ed-4fcf-bfab-85e24795b601",
      "search_target_title": "Page Views by Country Map",
      ...
      "score": 0.03105,
      "url": "https://stats.wikimedia.org/#/language.project.org/reading/page-views-by-country/normal|map|last-month|~total|monthly",
      "resolved_target_action": "https://stats.wikimedia.org/#/it.wikipedia.org/reading/page-views-by-country/normal|map|last-month|~total|monthly",
      "resolved_target_action_type": "URL",
      "target_input_matches": {
        "language": "it",
        "project": "wikipedia"
      }
    },
    {
      "rank": 3,
      "search_target_id": "77ff25d1-c1c9-4fa6-bf37-7509bcc00e32",
      "search_target_title": "Legacy Page Views (Pre-2016)",
      ...
      "score": 0.02971,
      "url": "https://stats.wikimedia.org/#/language.project.org/reading/legacy-page-views/normal|bar|2007-12-01~2016-08-31|~total|frequency",
      "resolved_target_action": "https://stats.wikimedia.org/#/it.wikipedia.org/reading/legacy-page-views/normal|bar|2007-12-01~2016-08-31|~total|monthly",
      "resolved_target_action_type": "URL",
      "target_input_matches": {
        "language": "it",
        "project": "wikipedia",
        "frequency": "monthly"
      }
    },
    {
      "rank": 4,
      "search_target_id": "a77395a5-9ba5-4fe2-bf89-9b9d0ac852aa",
      "search_target_title": "Top Viewed Articles",
      ...
      "score": 0.02955,
      "url": "https://stats.wikimedia.org/#/language.project.org/reading/top-viewed-articles/normal|table|last-month|~total|frequency",
      "resolved_target_action": "https://stats.wikimedia.org/#/it.wikipedia.org/reading/top-viewed-articles/normal|table|last-month|~total|monthly",
      "resolved_target_action_type": "URL",
      "target_input_matches": {
        "language": "it",
        "project": "wikipedia",
        "frequency": "monthly"
      }
    },
    {
      "rank": 5,
      "search_target_id": "d67367c8-53cc-4f3f-bf04-cdf4a8cdaa0d",
      "search_target_title": "Top Edited Pages",
      ...
      "score": 0.02814,
      "url": "https://stats.wikimedia.org/#/language.project.org/contributing/top-edited-pages/normal|table|last-month|~total|frequency",
      "resolved_target_action": "https://stats.wikimedia.org/#/it.wikipedia.org/contributing/top-edited-pages/normal|table|last-month|~total|monthly",
      "resolved_target_action_type": "URL",
      "target_input_matches": {
        "language": "it",
        "project": "wikipedia",
        "frequency": "monthly"
      }
    }
  ]
}

In the first result, language is it. The other inputs use their configured defaults: wikipedia, 2-year, and monthly. The target_input_matches object lists the input values used in the URL template. The resolved_target_action field contains the URL to open.

preview/

Show matching results as the user types. This endpoint searches the published version of the search space. The query and results are not saved for review in the Admin application.

GET <ORDS_BASE_URL>/trusted-search/search-api/preview/

Request headers

`X-Q`

string · Required

`X-N`

string · Required

Search space name, such as wikimedia. Maximum length: 100 characters. The space must have a published version.

`Authorization`

string · Required when JWT authentication is enabled

Bearer <ACCESS_TOKEN> for the signed-in user.

The X-Q request header contains the search query. The X-N request header contains the search space name. Both endpoints search the published version of the search space.

Returns

A JSON object with content type application/json.

`version`

integer · Always returned

Response format version. Currently 1. This is not the search space version ID.

`id`

string · Always returned

Identifier for this preview request. It does not identify a saved search.

`user_query`

string · Always returned

Query used for the search after any configured word substitutions. It can differ from X-Q.

`search_matches`

array of objects · Always returned

Ranked matches with the same match fields as search/. Empty if no targets matched.

Child fields

`rank`

integer · Always returned

Result position, starting at 1. Use this field to order results.

`search_target_id`

string · Always returned

Identifier of the matched search target.

`search_target_title`

string · Always returned

Search target title to display.

`score`

number · Always returned

Ranking score, rounded to five decimal places. When hybrid search is enabled, keyword and semantic results contribute to the ranking. With hybrid search disabled, ranking uses keyword-only matching.

`url`

string · URL target only

Configured URL template. It can contain unresolved input names.

`sql`

string · SQL target only

Configured SQL template before input values are inserted. Bind the input values separately when executing this template.

`resolved_target_action`

string or null · Always returned

For a URL target, the URL to open when the user selects the result. For a SQL target, a preview of the SQL statement. Null when no action is available.

`resolved_target_action_type`

string or null · Always returned

URL, SQL, or null when no action is available.

`target_input_matches`

object · Always returned

Example request

curl --request GET \
  --header "Authorization: Bearer <ACCESS_TOKEN>" \
  --header "X-Q: italian page views" \
  --header "X-N: wikimedia" \
  "<ORDS_BASE_URL>/trusted-search/search-api/preview/"

Example response

... indicates omitted fields. The values in this example are illustrative. <PREVIEW_ID> represents the identifier generated for this preview request.

{
  "version": 1,
  "id": "<PREVIEW_ID>",
  "user_query": "italian page views",
  "search_matches": [
    {
      "rank": 1,
      "search_target_id": "bd50fd19-14d7-4fd1-bf51-2f92c3becc50",
      "search_target_title": "Total Page Views",
      ...
      "score": 0.03227,
      "url": "https://stats.wikimedia.org/#/language.project.org/reading/total-page-views/normal|bar|period|~total|frequency",
      "resolved_target_action": "https://stats.wikimedia.org/#/it.wikipedia.org/reading/total-page-views/normal|bar|2-year|~total|monthly",
      "resolved_target_action_type": "URL",
      "target_input_matches": {
        "language": "it",
        "project": "wikipedia",
        "period": "2-year",
        "frequency": "monthly"
      }
    },
    {
      "rank": 2,
      "search_target_id": "2afc32e3-83ed-4fcf-bfab-85e24795b601",
      "search_target_title": "Page Views by Country Map",
      ...
      "score": 0.03105,
      "url": "https://stats.wikimedia.org/#/language.project.org/reading/page-views-by-country/normal|map|last-month|~total|monthly",
      "resolved_target_action": "https://stats.wikimedia.org/#/it.wikipedia.org/reading/page-views-by-country/normal|map|last-month|~total|monthly",
      "resolved_target_action_type": "URL",
      "target_input_matches": {
        "language": "it",
        "project": "wikipedia"
      }
    },
    {
      "rank": 3,
      "search_target_id": "77ff25d1-c1c9-4fa6-bf37-7509bcc00e32",
      "search_target_title": "Legacy Page Views (Pre-2016)",
      ...
      "score": 0.02971,
      "url": "https://stats.wikimedia.org/#/language.project.org/reading/legacy-page-views/normal|bar|2007-12-01~2016-08-31|~total|frequency",
      "resolved_target_action": "https://stats.wikimedia.org/#/it.wikipedia.org/reading/legacy-page-views/normal|bar|2007-12-01~2016-08-31|~total|monthly",
      "resolved_target_action_type": "URL",
      "target_input_matches": {
        "language": "it",
        "project": "wikipedia",
        "frequency": "monthly"
      }
    },
    {
      "rank": 4,
      "search_target_id": "a77395a5-9ba5-4fe2-bf89-9b9d0ac852aa",
      "search_target_title": "Top Viewed Articles",
      ...
      "score": 0.02955,
      "url": "https://stats.wikimedia.org/#/language.project.org/reading/top-viewed-articles/normal|table|last-month|~total|frequency",
      "resolved_target_action": "https://stats.wikimedia.org/#/it.wikipedia.org/reading/top-viewed-articles/normal|table|last-month|~total|monthly",
      "resolved_target_action_type": "URL",
      "target_input_matches": {
        "language": "it",
        "project": "wikipedia",
        "frequency": "monthly"
      }
    },
    {
      "rank": 5,
      "search_target_id": "d67367c8-53cc-4f3f-bf04-cdf4a8cdaa0d",
      "search_target_title": "Top Edited Pages",
      ...
      "score": 0.02814,
      "url": "https://stats.wikimedia.org/#/language.project.org/contributing/top-edited-pages/normal|table|last-month|~total|frequency",
      "resolved_target_action": "https://stats.wikimedia.org/#/it.wikipedia.org/contributing/top-edited-pages/normal|table|last-month|~total|monthly",
      "resolved_target_action_type": "URL",
      "target_input_matches": {
        "language": "it",
        "project": "wikipedia",
        "frequency": "monthly"
      }
    }
  ]
}

Use search/ to save the query and results for review in the Admin application. A preview id is not a saved search_id.

PL/SQL API

Call DBMS_TRUSTED_SEARCH.SEARCH from your application to retrieve ranked search targets. The procedure saves the query and results. You can review them in the Admin application. The p_search_record output parameter contains the search results in JSON format.

For the SQL*Plus example, connect as a database user with access to the search space and version. Applications can call the procedure through a database driver such as JDBC or python-oracledb. The procedure checks the caller’s access to the requested search space and version.

PROCEDURE search (
    p_user_query              IN  VARCHAR2,
    p_search_space            IN  VARCHAR2,
    p_search_space_version_id IN  VARCHAR2 DEFAULT NULL,
    p_search_record           OUT JSON
);

Parameters

`p_user_query`

VARCHAR2 · IN · Required

The text to search for. It must not be blank or a vector-like value such as [1,2,3]. Maximum length: 2,000 characters after any configured word substitutions.

`p_search_space`

VARCHAR2 · IN · Required

Search space name, such as wikimedia. The caller must have access to it.

`p_search_space_version_id`

VARCHAR2 · IN · Optional · Default: NULL

Search space version ID. Omit it or pass NULL to use the published version. If supplied, the ID must belong to the specified search space. The caller must have access to that version.

`p_search_record`

JSON · OUT · Required

Output parameter containing the search results in JSON format.

Find version IDs on Search Space Versions in the Admin application.

Search Output JSON

Returns

The p_search_record output parameter contains the following JSON object.

`version`

integer · Always returned

Response format version. Currently 1. This is not the search space version ID.

`id`

string · Always returned

Identifier of the saved search. The REST search/ endpoint returns this value as search_id.

`user_query`

string · Always returned

Query used for the search after any configured word substitutions. It can differ from p_user_query.

`search_matches`

array of objects · Always returned

Ranked search targets. Empty if no targets matched.

Child fields

`rank`

integer · Always returned

Result position, starting at 1. Use this field to order results.

`search_target_id`

string · Always returned

Identifier of the matched search target.

`search_target_title`

string · Always returned

Search target title to display.

`score`

number · Always returned

Ranking score, rounded to five decimal places. When hybrid search is enabled, keyword and semantic results contribute to the ranking. With hybrid search disabled, ranking uses keyword-only matching.

`url`

string · URL target only

Configured URL template. It can contain unresolved input names.

`sql`

string · SQL target only

Configured SQL template before input values are inserted. Bind the input values separately when executing this template.

`resolved_target_action`

string or null · Always returned

For a URL target, the URL to open when the user selects the result. For a SQL target, a preview of the SQL statement. Null when no action is available.

`resolved_target_action_type`

string or null · Always returned

URL, SQL, or null when no action is available.

`target_input_matches`

object · Always returned

Example call

To display the output in SQL*Plus, convert the JSON value to a CLOB.

SET LONG 1000000
SET LONGCHUNKSIZE 32767
VARIABLE search_record_json CLOB

DECLARE
  l_result JSON;
BEGIN
  dbms_trusted_search.search(
    p_user_query    => 'italian page views',
    p_search_space  => 'wikimedia',
    p_search_record => l_result
  );

  SELECT JSON_SERIALIZE(l_result RETURNING CLOB PRETTY)
    INTO :search_record_json
    FROM dual;
END;
/
PRINT search_record_json

Example output

This example shows five Wikimedia matches. ... indicates omitted fields. The values are illustrative. Your results depend on the published search space and its configuration.

{
  "version": 1,
  "id": "432d0380-555e-4f7f-bf05-f15d61802b4e",
  "user_query": "italian page views",
  "search_matches": [
    {
      "rank": 1,
      "search_target_id": "bd50fd19-14d7-4fd1-bf51-2f92c3becc50",
      "search_target_title": "Total Page Views",
      ...
      "score": 0.03227,
      "url": "https://stats.wikimedia.org/#/language.project.org/reading/total-page-views/normal|bar|period|~total|frequency",
      "resolved_target_action": "https://stats.wikimedia.org/#/it.wikipedia.org/reading/total-page-views/normal|bar|2-year|~total|monthly",
      "resolved_target_action_type": "URL",
      "target_input_matches": {
        "language": "it",
        "project": "wikipedia",
        "period": "2-year",
        "frequency": "monthly"
      }
    },
    {
      "rank": 2,
      "search_target_id": "2afc32e3-83ed-4fcf-bfab-85e24795b601",
      "search_target_title": "Page Views by Country Map",
      ...
      "score": 0.03105,
      "url": "https://stats.wikimedia.org/#/language.project.org/reading/page-views-by-country/normal|map|last-month|~total|monthly",
      "resolved_target_action": "https://stats.wikimedia.org/#/it.wikipedia.org/reading/page-views-by-country/normal|map|last-month|~total|monthly",
      "resolved_target_action_type": "URL",
      "target_input_matches": {
        "language": "it",
        "project": "wikipedia"
      }
    },
    {
      "rank": 3,
      "search_target_id": "77ff25d1-c1c9-4fa6-bf37-7509bcc00e32",
      "search_target_title": "Legacy Page Views (Pre-2016)",
      ...
      "score": 0.02971,
      "url": "https://stats.wikimedia.org/#/language.project.org/reading/legacy-page-views/normal|bar|2007-12-01~2016-08-31|~total|frequency",
      "resolved_target_action": "https://stats.wikimedia.org/#/it.wikipedia.org/reading/legacy-page-views/normal|bar|2007-12-01~2016-08-31|~total|monthly",
      "resolved_target_action_type": "URL",
      "target_input_matches": {
        "language": "it",
        "project": "wikipedia",
        "frequency": "monthly"
      }
    },
    {
      "rank": 4,
      "search_target_id": "a77395a5-9ba5-4fe2-bf89-9b9d0ac852aa",
      "search_target_title": "Top Viewed Articles",
      ...
      "score": 0.02955,
      "url": "https://stats.wikimedia.org/#/language.project.org/reading/top-viewed-articles/normal|table|last-month|~total|frequency",
      "resolved_target_action": "https://stats.wikimedia.org/#/it.wikipedia.org/reading/top-viewed-articles/normal|table|last-month|~total|monthly",
      "resolved_target_action_type": "URL",
      "target_input_matches": {
        "language": "it",
        "project": "wikipedia",
        "frequency": "monthly"
      }
    },
    {
      "rank": 5,
      "search_target_id": "d67367c8-53cc-4f3f-bf04-cdf4a8cdaa0d",
      "search_target_title": "Top Edited Pages",
      ...
      "score": 0.02814,
      "url": "https://stats.wikimedia.org/#/language.project.org/contributing/top-edited-pages/normal|table|last-month|~total|frequency",
      "resolved_target_action": "https://stats.wikimedia.org/#/it.wikipedia.org/contributing/top-edited-pages/normal|table|last-month|~total|monthly",
      "resolved_target_action_type": "URL",
      "target_input_matches": {
        "language": "it",
        "project": "wikipedia",
        "frequency": "monthly"
      }
    }
  ]
}

API Errors

REST APIs return HTTP responses and can include a JSON error object. The PL/SQL procedure raises database exceptions.

REST responses

Check the HTTP status and the JSON body. ORDS can reject authentication before the search runs. A missing or invalid bearer token on a protected endpoint can return 401 Unauthorized.

REST error object

`error`

string

internal_server_error when search or preview execution fails.

`detail`

string

Database error message.

These endpoints can return the error object with HTTP 200. A 200 status alone does not confirm that the search succeeded.

Example REST error response

{
  "error": "internal_server_error",
  "detail": "ORA-20004: Invalid value (NULL) for parameter (p_query). Violated criteria: Value must not be NULL."
}

PL/SQL exceptions

The procedure raises database exceptions. It does not return the REST error and detail object. Handle the exception before using the output variable.

Database error codes

For REST failures, the code can appear in the detail field. For PL/SQL failures, it is raised as a database exception.

`ORA-20003`

Access to the search space or version is denied. Check the user identity and search space access.

`ORA-20004`

Invalid input, such as a blank or vector-like query, or no published version. For PL/SQL calls, an explicit version ID can also be invalid or belong to a different search space.

`ORA-20005`

The query exceeds 2,000 characters. Shorten the query.

`ORA-20006`

A required resource cannot be found. Check the search space name in X-N for REST requests or p_search_space for PL/SQL calls.

`ORA-20000`

Internal error. Ask the administrator to investigate.

Search Widgets

Use the Trusted Answer Search widgets when you want to embed search directly into an existing application page without building a custom search interface. The widget package includes:

Search Bar: a compact inline search box that can be placed in a page header, navigation area, or application page.
Search Icon: a floating launcher that opens a search panel.

Both widgets use the same ORDS-backed search endpoint and the same configuration attributes. They open URL targets and do not execute SQL.

Administrator Setup

The guided tas-install.sh installer installs and verifies the widget REST endpoints. Ask a Trusted Answer Search administrator to confirm the endpoint URL and authentication settings. Run the following steps only when endpoint authentication needs to be configured or changed.

Verify prerequisites Confirm that the guided Trusted Answer Search installation completed and that Oracle REST Data Services is available for the database. On Autonomous Database Serverless (ADB-S), ORDS is available by default. For on-premises deployments, configure ORDS as required for the database.
Locate the widget files In the extracted Trusted Answer Search release archive, locate the widget/ directory. It contains install_widget.conf, install_widget.sh, and the widget JavaScript files.
Configure the widget installer Edit install_widget.conf and provide the database connection, installer user, and TASADMIN password. Keep the configuration file outside the web directory and source control because it contains database passwords. The installer account requires CREATE ANY PROCEDURE and EXECUTE WITH GRANT OPTION on ORDS_METADATA.ORDS. Have a database administrator provide the required privileges for your environment.

Example:
```
DB_CONNECT_STRING='myadb_high'
INSTALLER_USER=ADMIN
INSTALLER_USER_PASSWORD='<admin_password>'
TASADMIN_PASSWORD='<tasadmin_password>'
```
Configure JWT authentication Obtain the issuer, API audience, public signing-key URL, and scope from your identity-provider administrator. Set JWT_AUTHENTICATION_ENABLED=TRUE in install_widget.conf and supply JWT_ISSUER, JWT_AUDIENCE, and JWT_JWK_URL together. The installer requires an explicit authentication mode and rejects missing or incomplete JWT parameters when JWT authentication is enabled.
```
JWT_AUTHENTICATION_ENABLED=TRUE
JWT_ISSUER='<issuer-from-discovery>'
JWT_AUDIENCE='<api-primary-audience>'
JWT_JWK_URL='<jwks-uri-from-discovery>'
JWT_SCOPE_NAME=search_access
```
For applications that require sign-in, keep JWT authentication enabled so requests use an authenticated user identity. Setting JWT_AUTHENTICATION_ENABLED=FALSE explicitly disables JWT authentication; supplied JWT values are then ignored. Anonymous search and preview are limited to public search spaces with a published version. Private and unpublished versions remain inaccessible to anonymous requests.
Apply the endpoint configuration From the root of the extracted release archive, run:
```
cd widget
./install_widget.sh --config install_widget.conf
```
Record the widget REST endpoint URL reported by this installation under <ORDS_BASE_URL>/trusted-search/search-api/.

Application Developer Setup

After the administrator configures the endpoints, host the widget files and embed them in your application pages. These steps assume that your application already handles sign-in and can supply an access token when authentication is required. If its current token is accepted by the Trusted Answer Search endpoints, no additional identity-provider application registration is needed.

Host the widget JavaScript files From the release archive’s widget/ directory, copy one or both JavaScript files to a web server or static asset location that your application can load:
- search_bar_widget.js
- search_icon_widget.js
Serve the files over HTTPS when the application page is served over HTTPS.
Configure authentication before loading the widget When JWT authentication is enabled, the host application must obtain an access token for the signed-in end user. The widget does not display a login screen or contact the identity provider. Complete login before loading the widget.

Use Authorization Code with PKCE for a browser application. Supply an access token, not an ID token or a client credentials token.

Define window.SEARCH_WIDGET_CONFIG before loading the widget script. Its getAuthHeaders function must synchronously return the headers containing the current bearer token. The host application’s authentication library manages login and token renewal.
```
<script>
  window.SEARCH_WIDGET_CONFIG = {
    showTargetInputs: true,
    placeholder: "Powered by Oracle Trusted Answer Search",
    debounceMs: 150,
    getAuthHeaders: function () {
      const token = window.myApplicationAuth.getCurrentAccessToken();
      return token ? { Authorization: "Bearer " + token } : {};
    }
  };
</script>
```
window.myApplicationAuth.getCurrentAccessToken() represents your application’s authentication code; it is not a Trusted Answer Search API. Replace it with a synchronous accessor for your current access token.
Embed the widget Add the script tag for the widget you want to use. Set data-ords-search-url to the Trusted Answer Search ORDS search endpoint and data-search-space to the search space that users should query.

Inline Search Bar:
```
<script
  src="/assets/js/search_bar_widget.js"
  data-ords-search-url="https://your-host.example.com/ords/trusted-search/search-api/search/"
  data-search-space="wikimedia">
</script>
```
Floating Search Icon:
```
<script
  src="/assets/js/search_icon_widget.js"
  data-ords-search-url="https://your-host.example.com/ords/trusted-search/search-api/search/"
  data-search-space="wikimedia">
</script>
```
The widget also uses preview/ and selection/ for preview and result-selection requests. Set their URLs with data-ords-preview-url and data-ords-selection-url. When these attributes are omitted, the widget derives the URLs from a search URL ending in /search/.

On ADB-S, find the ORDS base URL on the database details page under Tool Configuration, Web Access (ORDS), Public access URL.
Optionally configure widget display Set display options in the same window.SEARCH_WIDGET_CONFIG object before loading the widget. Preserve getAuthHeaders when customizing these options:
- showTargetInputs: set to true to display target input values beneath each result card.
- placeholder: sets the placeholder text for the Search Bar widget.
- debounceMs: sets the delay, in milliseconds, before the widget runs a search after the user stops typing.
Confirm network access and CORS Confirm that the application page can reach the Trusted Answer Search ORDS endpoint. If the widget is hosted from a different origin than ORDS, configure Cross-Origin Resource Sharing (CORS) for the Trusted Answer Search API.

As an authorized Trusted Answer Search administrator, set TRUSTED_SEARCH_WIDGET_ALLOWED_ORIGINS to the exact, comma-separated origins. Include existing origins that must retain access; this example supplies two origins:
```
BEGIN
  dbms_trusted_search.update_config_parameter(
    p_name  => 'TRUSTED_SEARCH_WIDGET_ALLOWED_ORIGINS',
    p_value => 'https://wikimedia-insights.example.com,https://wikimedia-reports.example.com:8443'
  );
END;
/
COMMIT;
```
Each origin contains the scheme, host, and optional port, without a path or wildcard. Verify that preflight requests permit the API headers, including Authorization, X-Q, X-N, and Content-Type.

Configure the identity provider’s allowed origins separately when the browser calls its endpoints.

Test the Widget

Load the application page and run a query. Confirm that results come from the configured search space and that selecting a result opens its report.

Search Bar

Enter italian page views in the Search Bar. The following example shows results from the Wikimedia search space.

Description of the illustration search-bar-widget.png

To report an unsuccessful search, select I didn’t find what I was looking for at the end of the results.

Troubleshooting Widget Integration

Widget does not load: confirm that the JavaScript file URL is valid and that the file is served over HTTPS when the host page uses HTTPS.
Search requests fail in the browser: check the browser developer tools for network, authentication, or CORS errors.
401 Unauthorized: confirm that the application sends a valid bearer token and that the token issuer, audience, signing key URL, and scope match the JWT configuration in install_widget.conf.
remote_ident is null from the identity/ endpoint: confirm that JWT authentication is enabled for the endpoint and that the request is using an end-user token rather than a client credentials flow token.
SQL*Plus Not Found during installation: confirm that SQL*Plus is installed and available in the shell environment where you run install_widget.sh.
TRUSTED_SEARCH Schema Not Found during installation: run the Trusted Answer Search back-end installer before running the widget installer.

Configure SSO for an Application Hosting the Search Widget

This optional example adds sign-in to a local widget page using Oracle Cloud Infrastructure Identity and Access Management (OCI IAM). Use it when the application does not already have a sign-in setup that supplies an access token accepted by the Trusted Answer Search endpoints.

The example uses an OCI IAM identity domain, a Trusted Answer Search database with Oracle REST Data Services (ORDS), and a locally hosted web page. The host page signs in the user and obtains an access token. ORDS validates the access token before processing requests to the Trusted Answer Search REST API.

The browser uses the OAuth 2.0 Authorization Code flow with Proof Key for Code Exchange (PKCE). Database credentials remain in the installation environment; the browser does not connect directly to the database.

Before You Begin

Prepare the following:

An installed Trusted Answer Search back end and administration application. See Get Started with Oracle Trusted Answer Search.
ORDS configured for the database and reachable from the browser.
The widget/ directory from the extracted Trusted Answer Search release archive.
An OCI IAM identity domain and permission to configure applications and CORS settings in that domain.
A published wikimedia Search Space and an end user with access to it. This SSO example uses Wikimedia for its search queries.
SQL*Plus on the widget installation computer and Python 3 on the computer that hosts the local example.
An installer account with CREATE ANY PROCEDURE and EXECUTE WITH GRANT OPTION on ORDS_METADATA.ORDS. Have a database administrator provide the required privileges for your environment.

The local page uses these values:

Setting	Value
Redirect URL	`http://localhost:8080/widget-example.html`
Browser origin	`http://localhost:8080`
API application name	`Trusted Answer Search Widget API`
Browser application name	`Trusted Answer Search Widget Client`
API scope suffix	`search_access`

Use localhost consistently in the redirect URL and browser origin. Replace the example database and identity-domain values with values from your environment. Trusted Answer Search Widget Client is the name of the OCI IAM browser client in this example.

The screenshots illustrate the example configuration. Use your own API audience and application values rather than copying environment-specific values from an image.

Note: HTTP is used only for the local example. Use HTTPS for a deployed application. This example does not implement automatic token refresh or identity-provider logout.

Register the Trusted Answer Search API in OCI IAM

Create a resource application to represent the Trusted Answer Search ORDS API.

Open your identity domain in the OCI Console and select Integrated applications.
Select Add application, Confidential Application, and Launch workflow.

The Confidential Application option is selected for the Trusted Answer Search API registration.

Description of the illustration widget-sso-confidential-application.png

Name the application Trusted Answer Search Widget API and enter a description for the Trusted Answer Search ORDS registration.

Description of the illustration widget-sso-resource-details.png
Configure the application as a resource server. For this example, set the access-token lifetime to 3600 seconds and leave token refresh disabled.
Set Primary audience to the value that you will configure as JWT_AUDIENCE in the widget installer. For example, use https://<public-ords-host>/ords/trusted-search/. Preserve the exact path, capitalization, and trailing slash.
Add the scope suffix search_access and enable user consent for this example. Record the full scope value from the registration for use by the browser application.
Leave client configuration disabled for this API registration. Save and activate the application. Confirm activation of Trusted Answer Search Widget API in the Activate application dialog.

For OCI IAM field descriptions, see Adding a Confidential Application.

Register the Browser Application

Create a separate public client for the page that hosts the widget.

From Integrated applications, select Add application, Mobile Application, and Launch workflow. Name the application Trusted Answer Search Widget Client.

Select Mobile Application for the public browser client.

Description of the illustration widget-sso-mobile-application.png
Enable the Authorization code grant. Leave the Implicit, Device code, and Refresh token grants disabled for this example.
For local development, enable Allow non-HTTPS URLs. Register http://localhost:8080/widget-example.html as the exact Redirect URL.

The client configuration shows the Authorization code grant selected and the localhost redirect URL entered for this example.

Description of the illustration widget-sso-code-redirect.png
Leave logout URLs empty for this local-session example and keep Bypass consent disabled. Select a client IP policy that permits requests from the example host.
In the Token issuance policy section, use Add scope to associate the Trusted Answer Search API scope created in the previous section. Creating the API scope alone does not associate it with this client. Do not grant IAM administrator application roles to this browser client.
Finish and activate the application. Assign the intended users or groups if application grants are enforced, and record the browser application’s Client ID.

OCI IAM uses the Mobile Application type for a public client that cannot keep a client secret. Do not add a client secret to the web page. See Adding a Mobile Application.

The browser example uses Authorization Code with PKCE S256. See Authorization Code Grant Type.

Configure IAM Browser Access and Collect Metadata

Allow the local page to call IAM and obtain the values needed by the widget installer and browser application.

In the identity domain’s session settings, enable Allow cross-origin resource sharing (CORS) and add http://localhost:8080 to the allowed origins. Preserve existing entries and save the change. See Changing Data Sharing Settings.

The Data sharing settings section shows CORS enabled and http://localhost:8080 in Allowed CORS domain names.

Description of the illustration widget-sso-iam-cors.png

Read the identity domain’s OpenID Connect discovery document. Replace <identity-domain-host> with your domain host. This command requires curl and jq.

curl -sS \
  -H 'Accept: application/json' \
  'https://<identity-domain-host>/.well-known/openid-configuration' |
jq '{issuer, jwks_uri, authorization_endpoint, token_endpoint}'

Record the returned values without changing their paths or trailing slashes.
Verify that the JWK Set URL can be read without interactive login and is reachable from the database/ORDS environment. Browser access alone does not verify this connectivity.

Discovery or registration value	Where to use it
`issuer`	Widget installer `JWT_ISSUER`
`jwks_uri`	Widget installer `JWT_JWK_URL`
API primary audience	Widget installer `JWT_AUDIENCE`
API scope suffix `search_access`	Widget installer `JWT_SCOPE_NAME`
Full API scope from the registration	Browser authorization request, together with `openid profile`
`authorization_endpoint`	Browser sign-in request
`token_endpoint`	Browser authorization-code exchange
Browser application Client ID	Browser authorization and token requests

Apply the JWT Settings

Use the values collected for this example to update install_widget.conf in the release archive’s widget/ directory:

Setting	Value
`JWT_AUTHENTICATION_ENABLED`	`TRUE`
`JWT_ISSUER`	`issuer` from the discovery document
`JWT_AUDIENCE`	Primary audience of `Trusted Answer Search Widget API`
`JWT_JWK_URL`	`jwks_uri` from the discovery document
`JWT_SCOPE_NAME`	`search_access`

Apply the configuration using the procedure in Administrator Setup. If the endpoints already use these JWT settings, skip this configuration step.

Record the API base URL printed by the installer, including its trailing slash. For example:

https://<public-ords-host>/ords/trusted-search/search-api/

Allow the Local Origin in Trusted Answer Search

Configure CORS separately for the Trusted Answer Search API. The IAM setting in the preceding section permits calls to IAM; it does not configure browser access to ORDS.

Connect as TASADMIN and update TRUSTED_SEARCH_WIDGET_ALLOWED_ORIGINS. When other origins are already configured, include them in the comma-separated value to retain their access.

BEGIN
  dbms_trusted_search.update_config_parameter(
    p_name  => 'TRUSTED_SEARCH_WIDGET_ALLOWED_ORIGINS',
    p_value => 'http://localhost:8080'
  );
END;
/
COMMIT;

An origin contains the scheme, host, and optional port, without a path. Use exact origins rather than a wildcard. The browser’s preflight request must permit the headers used by the API, including Authorization, X-Q, X-N, and Content-Type.

Create the Example Website

Create a separate website directory with the following layout. Copy search_bar_widget.js from the matching release’s widget package into assets. Create the other three files using the code in this section.

website/
  widget-example.html
  auth.js
  serve.py
  assets/
    search_bar_widget.js

Keep database configuration files, passwords, and wallets outside this directory. The local server serves files from the directory that contains serve.py.

Create the Host Page

Save the following as widget-example.html. The page loads auth.js, which completes sign-in and calls identity/ before loading the widget.

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="referrer" content="no-referrer">
<title>Wikimedia | Trusted Answer Search</title>
<style>
:root{font-family:system-ui,sans-serif;color:#252a2c;background:#f5f4f0}body{margin:0}header{background:#183b38;color:white;padding:24px 7%;display:flex;justify-content:space-between;align-items:center}header span{font-size:13px;letter-spacing:.1em}main{max-width:880px;margin:70px auto;padding:0 24px}h1{font-size:44px;letter-spacing:-.04em;margin-bottom:12px}p{line-height:1.6}button{background:#bf4938;color:white;border:0;border-radius:7px;padding:12px 20px;font:inherit;cursor:pointer}button:disabled{opacity:.6;cursor:wait}.card{background:white;padding:28px;border:1px solid #ddd;border-radius:12px;margin-top:30px}#status{padding:14px 0}#status[data-error=true]{color:#a3261d}pre{white-space:pre-wrap;overflow-wrap:anywhere;font-size:13px}#widget-container{min-height:90px}footer{color:#656a69;font-size:13px;margin-top:32px}
</style>
<script src="/auth.js" defer></script>
</head>
<body>
<header><span>ORACLE TRUSTED ANSWER SEARCH</span><button id="session-button">Sign in with OCI IAM</button></header>
<main><h1>Explore Wikimedia</h1><p>Sign in with your OCI IAM account, then search the Wikimedia Search Space.</p>
<div id="status" role="status" aria-live="polite">Ready to sign in.</div>
<section class="card"><div id="widget-container">Search will appear after sign-in and the Trusted Answer Search identity check.</div></section>
<details id="identity-panel" hidden><summary>Trusted Answer Search identity response</summary><pre id="identity"></pre></details>
<footer>Demo: access tokens remain in memory. When the session expires, sign in again. Clearing this page’s session does not sign you out of OCI IAM.</footer>
</main></body></html>

Add the Authentication Code

Save the following as auth.js. Replace each placeholder in CONFIG before running the example.

Setting	Value to supply
`clientId`	Client ID of the `Trusted Answer Search Widget Client` public application.
`authorizationEndpoint`	`authorization_endpoint` from your identity domain’s discovery document.
`tokenEndpoint`	`token_endpoint` from the same discovery document.
`redirectUri`	Exact registered redirect URL; retain the supplied localhost URL for this example.
`scope`	`openid profile` followed by the full Trusted Answer Search API scope associated with the public client. Replace `<scope>` with the full registered scope, not just its suffix.
`apiBase`	Installed API base URL ending in `/trusted-search/search-api/`, including the trailing slash.
`searchSpace`	The published `wikimedia` Search Space that the signed-in user can access.

The example stores the access token in memory. Session storage holds only the temporary PKCE transaction. The synchronous getAuthHeaders function supplies the current bearer token to widget requests.

'use strict';
const CONFIG = Object.freeze({
  clientId: '<client-ID>',
  authorizationEndpoint: '<AuthorizationEndpoint>',
  tokenEndpoint: '<TokenEndpoint>',
  redirectUri: 'http://localhost:8080/widget-example.html',
  scope: 'openid profile <scope>',
  apiBase: '<ORDS_ENDPOINT>',
  searchSpace: 'wikimedia'
});
const statusElement = document.querySelector('#status');
const button = document.querySelector('#session-button');
const container = document.querySelector('#widget-container');
const transactionKey = 'tas-demo-pkce';
let accessToken = '';
let expiresAt = 0;
let expiryTimer;
function status(message, error = false) { statusElement.textContent = message; statusElement.dataset.error = String(error); }
function base64url(bytes) { return btoa(String.fromCharCode(...bytes)).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, ''); }
function random() { return base64url(crypto.getRandomValues(new Uint8Array(32))); }
function clearSession() {
  accessToken = ''; expiresAt = 0; clearTimeout(expiryTimer);
  sessionStorage.removeItem(transactionKey);
  location.replace(CONFIG.redirectUri);
}
async function signIn() {
  if (`${location.origin}${location.pathname}` !== CONFIG.redirectUri) throw new Error('Open http://localhost:8080/widget-example.html to sign in.');
  button.disabled = true;
  const verifier = random();
  const state = random();
  const challenge = base64url(new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))));
  sessionStorage.setItem(transactionKey, JSON.stringify({ verifier, state, createdAt: Date.now() }));
  const url = new URL(CONFIG.authorizationEndpoint);
  url.search = new URLSearchParams({client_id: CONFIG.clientId, response_type: 'code', redirect_uri: CONFIG.redirectUri,
    scope: CONFIG.scope, state, nonce: random(), code_challenge: challenge, code_challenge_method: 'S256'}).toString();
  location.assign(url.href);
}
function showError(error) {
  status(error instanceof TypeError ? 'Network request failed. Check IAM or Trusted Answer Search CORS settings and browser Network details.' : error.message, true);
  button.disabled = false;
}
button.addEventListener('click', () => {
  if (accessToken) clearSession();
  else signIn().catch(showError);
});
function expire() {
  accessToken = ''; expiresAt = 0;
  container.replaceChildren(document.createTextNode('Session expired. Sign in again to continue searching.'));
  button.textContent = 'Sign in with OCI IAM'; button.disabled = false;
  document.querySelector('#identity-panel').hidden = true;
  document.querySelector('#identity').textContent = '';
  status('Session expired. Sign in again.');
}
function getAuthHeaders() {
  if (!accessToken || Date.now() >= expiresAt) { if (accessToken) expire(); return {}; }
  return { Authorization: `Bearer ${accessToken}` };
}
async function initialize() {
  const params = new URLSearchParams(location.search);
  const code = params.get('code');
  const oauthError = params.get('error');
  if (!code && !oauthError) return;
  const saved = sessionStorage.getItem(transactionKey);
  sessionStorage.removeItem(transactionKey);
  history.replaceState({}, '', CONFIG.redirectUri);
  const transaction = saved ? JSON.parse(saved) : null;
  if (!transaction || transaction.state !== params.get('state') || Date.now() - transaction.createdAt > 600000) {
    throw new Error('Login response is missing a valid, recent state. Please sign in again.');
  }
  if (oauthError) {
    const detail = (params.get('error_description') || '').slice(0, 1200);
    throw new Error(`OCI sign-in was not completed (${oauthError}). ${detail || 'Check that Trusted Answer Search Widget Client is active and permits the Authorization code grant.'}`);
  }
  button.disabled = true; status('Completing OCI sign-in…');
  const response = await fetch(CONFIG.tokenEndpoint, {
    method: 'POST', credentials: 'omit', cache: 'no-store',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({grant_type: 'authorization_code', client_id: CONFIG.clientId,
      redirect_uri: CONFIG.redirectUri, code, code_verifier: transaction.verifier})
  });
  if (!response.ok) throw new Error(`Token exchange failed (HTTP ${response.status}). Check the client registration, redirect URL and scope.`);
  const tokens = await response.json();
  const lifetime = Number(tokens.expires_in);
  if (!tokens.access_token || !Number.isFinite(lifetime) || lifetime <= 30) throw new Error('IAM did not return a usable access token and lifetime.');
  accessToken = tokens.access_token;
  expiresAt = Date.now() + (lifetime - 30) * 1000;
  expiryTimer = setTimeout(expire, Math.min(expiresAt - Date.now(), 2147483647));
  button.textContent = 'Clear local session'; button.disabled = false;
  status('Signed in to OCI IAM. Checking Trusted Answer Search identity…');
  const identityResponse = await fetch(`${CONFIG.apiBase}identity/`, { headers: getAuthHeaders(), credentials: 'omit', cache: 'no-store' });
  if (!identityResponse.ok) throw new Error(`Trusted Answer Search identity check failed (HTTP ${identityResponse.status}). Check JWT audience, issuer, scope and key access.`);
  const identity = await identityResponse.json();
  document.querySelector('#identity').textContent = JSON.stringify(identity, null, 2);
  document.querySelector('#identity-panel').hidden = false;
  window.SEARCH_WIDGET_CONFIG = {placeholder: 'Search Wikimedia…', debounceMs: 300, telemetryEnabled: true, getAuthHeaders};
  container.replaceChildren();
  const script = document.createElement('script');
  script.src = 'assets/search_bar_widget.js';
  script.dataset.ordsSearchUrl = `${CONFIG.apiBase}search/`;
  script.dataset.ordsPreviewUrl = `${CONFIG.apiBase}preview/`;
  script.dataset.ordsSelectionUrl = `${CONFIG.apiBase}selection/`;
  script.dataset.searchSpace = CONFIG.searchSpace;
  script.addEventListener('load', () => status('Trusted Answer Search accepted your token. Search Wikimedia below; expand the identity response to verify your user.'));
  script.addEventListener('error', () => status('The widget script failed to load.', true));
  container.append(script);
}
initialize().catch(showError);

The widget uses data-ords-search-url, data-ords-preview-url, and data-ords-selection-url for search, preview, and selection requests. This example sets all three explicitly from apiBase.

Add the Local Server

Save the following as serve.py. It binds to the loopback interface, suppresses request logging, and adds headers to prevent caching and referrer transmission.

from http.server import ThreadingHTTPServer, SimpleHTTPRequestHandler
from pathlib import Path
class DemoHandler(SimpleHTTPRequestHandler):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, directory=str(Path(__file__).parent), **kwargs)
    def log_message(self, *args):
        pass
    def end_headers(self):
        self.send_header('Cache-Control', 'no-store')
        self.send_header('Referrer-Policy', 'no-referrer')
        super().end_headers()
server = ThreadingHTTPServer(('127.0.0.1', 8080), DemoHandler)
print('Trusted Answer Search demo ready at http://localhost:8080/widget-example.html', flush=True)
server.serve_forever()

Run and Verify the Example

From the website directory, start the server:
```
python3 serve.py
```
Open http://localhost:8080/widget-example.html. Use localhost, rather than 127.0.0.1, so that the URL matches the registered redirect.
Select Sign in with OCI IAM and complete sign-in and consent.
After returning to the page, expand Trusted Answer Search identity response. Verify that remote_ident and the resolved Trusted Answer Search identity identify the intended end user.
Search for a query supported by your Search Space. For Wikimedia, try italian page views and verify the results against your configured targets.
Verify preview and result-selection responses. Successful sign-in alone does not verify these operations or access to a Search Space.
Verify that requests with expired tokens or insufficient scope are rejected, and that an unapproved browser origin cannot read API responses.

If port 8080 is already in use, stop the conflicting local server before starting this example. Changing the port also requires updating the redirect URL and the IAM and Trusted Answer Search allowed origins.

Note: CORS controls browser access to responses. It does not replace token validation or authorization.

Session Handling and Limitations

This example demonstrates the login handoff. It does not implement automatic token refresh or identity-provider logout.

The local session expires 30 seconds before the reported access-token lifetime ends. The user must sign in again to continue.
Clear local session clears this page’s session and reloads the page. It does not end the OCI IAM SSO session.
The host page supplies the access token; ORDS validates it. The example does not use the ID token as proof of identity.
For a production application, use the host application’s authentication library to manage login, token renewal, and logout. Load the widget only after an access token is available.

Troubleshoot the Example

Symptom	Check
`unauthorized_client` with a scope error	Associate the correct Trusted Answer Search API scope with the public client. Compare the full requested scope and API audience with the registration.
Other `unauthorized_client` errors	Check the application activation, Authorization code grant, Client ID, and exact redirect URL.
Token exchange fails with a browser network error	Check IAM CORS settings and the token request in the browser’s network tools.
`identity/` returns HTTP 401 or 403	Check the access token’s issuer, audience, scope, and expiry, along with signing-key reachability and the ORDS scope-to-privilege mapping.
Trusted Answer Search requests are blocked by the browser	Check the exact origin in `TRUSTED_SEARCH_WIDGET_ALLOWED_ORIGINS` and the preflight response.
Search does not return expected results	Check the Search Space name, published version, configured targets, and end-user access.
Widget script fails to load	Verify that `assets/search_bar_widget.js` is present and comes from the matching Trusted Answer Search release.

Do not include access tokens or database passwords when sharing diagnostic information.

Check the User Identity

Use the identity/ troubleshooting endpoint when the service recognizes the wrong user or a signed-in user receives an unexpected access error. It shows which user Trusted Answer Search recognizes for the request.

For example, if your application signs you in as TASUSER, check that the service also recognizes you as TASUSER. You do not need to call this endpoint before each search.

GET <ORDS_BASE_URL>/trusted-search/search-api/identity/

curl --request GET \
  --header "Authorization: Bearer <ACCESS_TOKEN>" \
  "<ORDS_BASE_URL>/trusted-search/search-api/identity/"

Example response

This example uses illustrative identities. The returned values depend on the signed-in user and deployment.

{
  "remote_ident": "TASUSER",
  "remote_user": null,
  "tas_ctx_username": "TASUSER",
  "tas_ctx_source": "ORDS",
  "client_identifier": "TASUSER",
  "session_user": "TASADMIN",
  "apex_app_user": null
}

Check the returned identity

remote_ident is the end-user identity supplied by ORDS after authentication.
tas_ctx_username is the user identity Trusted Answer Search uses to check search space access.
session_user is the database account handling the request. It can differ from the signed-in user.

In this example, the signed-in user is TASUSER, and the database account is TASADMIN. Check that remote_ident and tas_ctx_username identify the expected user. If they do not, check the access token sent by your application and the JWT configuration.

This endpoint does not run a search or confirm access to a search space. The search/ and preview/ endpoints check access to the requested search space.

When JWT authentication is enabled, a missing or invalid bearer token returns 401 Unauthorized.