# Content Access Control via APIs

Many systems employ complex content access control, such as `User Criteria` on ServiceNow or group-based access control on Confluence. These configurations can be intricate, often involving custom scripts for access evaluation. Such access control cannot be replicated outside the context of the source system.

To support such configurations, the Aisera platform has support for API-based access control. It is configured within a Data Source, and allows you to use the external system's built in APIs to apply access controls to the content ingested into the Aisera Platform.

For systems like ServiceNow, you can use this configuration for applying access control on both **Knowledge Articles** and **Service Catalog Items**.

{% hint style="info" %}
Make sure the user ingestion is setup on a schedule. To check whether a user has access to content, the platform uses the user’s id from the SOR. User ingestion makes sure  the platform can access a user’s external ID.
{% endhint %}

## Supported Use Cases for Access Control via API

In the following use cases, note that the applications/bot can recognize regions in user requests, such as APAC, EMEA, or EU.

<table><thead><tr><th width="234">Category</th><th>Supported Use Cases</th></tr></thead><tbody><tr><td>ServiceNow - Aisera API</td><td>This is limited to <a href="#servicenow-api">Aisera's Update Set</a> in ServiceNow</td></tr><tr><td>ServiceNow - Aisera Attributes</td><td>Region based responses, for example, regional Holidays. Group based responses using a tag-based solution, such as HR group.</td></tr><tr><td>Confluence Cloud - Aisera API</td><td><p>This is limited to the reference implementation listed in <a href="https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-content-permissions/#api-wiki-rest-api-content-id-permission-check-post">Atlassian API Documentation</a>. </p><ul><li>This only supports the <strong>Check Content Permissions</strong> API.</li><li>This only supports users with permissions to see "anyone" email.</li></ul><p>The prerequisites for this include the following:</p><ul><li>Users are ingested with user emails.</li><li>Ingested users have a Confluence Account ID as an external ID.</li><li>The Data Source with the <strong>User Learning</strong> function is defined as a <strong>System of Record (SOR).</strong></li><li>The email of the ingested user records should be the same email used for the data sources. </li></ul></td></tr><tr><td>Confluence Cloud - Aisera Attributes</td><td><p></p><p>Region based responses, for example, regional Holidays. Prerequisites for this use case include:</p><ul><li>The region or language attributes should be a custom field in the ingested articles</li><li>The region or language should be ingested in the <strong>User Profiles</strong></li></ul></td></tr><tr><td>Confluence On-Premises Installation - Aisera API</td><td>This is not supported.  On-premises installations of Confluence <em>do not have permissions to check APIs.</em></td></tr><tr><td>Confluence On-Premises Installation - Aisera Attributes</td><td><p>Region based responses, for example, regional Holidays. Prerequisites for this use case include:</p><ul><li>The region or language attributes should be a custom field in the ingested articles</li><li>The region or language should be ingested in the <strong>User Profiles</strong></li></ul></td></tr></tbody></table>

## Tenant Configuration <a href="#tenant-configuration" id="tenant-configuration"></a>

You will need to enable the **Enable Access Management** feature. Once enabled, Access Management will be enabled tenant wide, allowing for access control to be enabled on any data source.

This configuration is found under **Settings > Configuration > Access Management.**&#x20;

<div align="left"><figure><img src="/files/nM1NYWVNNfkzl6aFJgcy" alt=""><figcaption><p>Tenant Configuration Parameters</p></figcaption></figure></div>

## Data Source Configuration

After enabling access management, you will need to configure your data source for access management.

Navigate to **Settings > Data Sources** and choose the Data Source for which you want to enable access management. On the **Data Source Details** screen, click the **Pencil** icon in the upper right to edit, then select **Configuration.** Set **External API Access Management** to **Yes.**

<div align="left"><figure><img src="/files/1ygU34WuVhcMIEZopRQ5" alt=""><figcaption></figcaption></figure></div>

When you choose the Yes option for External API Access Management, you will see two additional fields, **API to check access** and **Attribute based contextual filter**. The ServiceNow example below, displays this screen with values in these fields.

<figure><img src="/files/zPtevkLkav5DOWKPw4ts" alt=""><figcaption><p>External API Access</p></figcaption></figure>

<table><thead><tr><th width="292.4000244140625">Parameter</th><th>Definition</th></tr></thead><tbody><tr><td>External API Access Management</td><td>This flag enables access control via an API <em>for all articles</em> ingested through this data source.</td></tr><tr><td>API to Check Access</td><td>This is the relative path of the API used to check if a user has access to content ingested by this data source. The external system endpoint will be prefixed with this relative URL to build the final URL. Check the sections below for more information about your specific use case.</td></tr><tr><td>Attribute Based Contextual Filter</td><td>In addition to checking if the user can view the content or not, you can apply an additional filter to it. The configured filter at the data source level will be applied to KB Articles ingested via this KB only.</td></tr></tbody></table>

### ServiceNow API

The ServiceNow data source does not have an out-of-the-box API to check user criteria based access controls. Instead, a scripted API will need to be installed on your system. Contact your Aisera team for the install package.&#x20;

Once the package has been installed, the relative API path will be: `/api/aisera/user_criteria_check/check`

#### **Validating the ServiceNow API**

After installing the update set provided to you by your Aisera team, you will need to validate the API is working as expected. To validate the API is working:

1. Navigate to **Rest API Explorer** within ServiceNow.
2. Select **aisera** from **Namespace.**
3. Select **User criteria check** from **API Name.**
4. Use the following sample payload.
   1. Replace `userId` with the the `sys_id` of a user on your system.
   2. Update the IDs under `knowledgeDocuments` with the IDs of knowledge articles within your system.
   3. If you want to test the Service Catalog, replace the IDs under `catalogItems` with the `sys_ids` of some Service Catalog items.
   4. Try these inputs with multiple users.<br>

      ```json
      {
          "userId": "0123456789abcdef0123456789abcdef",
          "knowledgeDocuments": [{
              "id": "KB1234"
          }, {
              "id": "KB1235"
          }],
          "catalogItems": [{
              "id": "0123456789abcdef0123456789abcdef"
          }]
      }
      ```
5. The output of the API should look similar to the the following example output. The `canView` field displays whether user has access to the specified content:<br>

   ```json
   {
       "userId": "a0f7e879db219150996f4a7f0596193f",
       "knowledgeDocuments": [{
           "id": "KB1233",
           "canView": true
       }, {
           "id": "KB4455",
           "canView": false
       }],
       "catalogItems": [{
           "id": "9e274809db6ddd10996f4a7f059619fa",
           "canView": true
       }]
   }
   ```

#### User Criteria with Scripts

You may be using a script in your User Criteria. If you are not using the predefined `user_id` for your user's ID in the script, the user criteria will not work properly when checked by an API. It is recommended that you use the pre-defined `user_id`.

Refer to this ServiceNow [documentation](https://docs.servicenow.com/bundle/washingtondc-servicenow-platform/page/product/service-catalog-management/task/t_CreateAUserCriteriaRecord.html).

### Confluence API

This API is provided by Atlassian. the API value will be: `rest/api/content/{}/permission/check`

## Optional Filters

Optional filters are filters applied using [Access Attributes](/aisera-platform/adding-data-to-your-tenant/content-access-control.md) specified on the Aisera Platform. Filters may include attributes like language, location, department, and others. These filters are applied by using Access attributes that are marked as ***Enabled**, but not **Required***. These are considered "Soft Filters" because they allow for a fallback response when a document meeting the exact filter requirements cannot be found.

For example, you may want a bot to prioritize documents in the user's native language. If a user asks a question in German, the bot will first search for a German version of the answer. However, if no German article exists, the optional status of the access attribute allows the bot to ignore the language constraint and fallback to providing an English document instead. This ensures the user gets an answer even if a match is not available.

The Aisera platform uses [Java Expression Language (JEXL)](https://commons.apache.org/proper/commons-jexl/) based expressions to define such filters. You can define Access Attribute based filters at the tenant level. To do so, navigate to **Settings > Configuration > Access Management > Access Policy For Optional Attributes.**

Note that you can also set [**Access Attributes at the application/bot (not Tenant) level**](/aiseragpt/how-to-set-up-an-aiseragpt-bot/add-application-access-attributes.md#pdf-page-teny1gndmmru7bngzxak-to-assign-access-attributes-to-your-virtual-assistant).

### Sample Implementation <a href="#single-value-attribute" id="single-value-attribute"></a>

The following expression is an example of a filter:

{% code overflow="wrap" %}

```java
(entity.language == null || 
 entity.language == '' || 
 entity.language == 'en' || 
 entity.language == user.language)
```

{% endcode %}

With these expressions, you define the following:

1. `entity.language == null`: If a Knowledge Base Article does not have the attribute `language` then the user can view it.
2. `entity.language == ''`: If a Knowledge Base Article has an empty value for the `language` attribute, then the user can view it.
3. `entity.language == 'en'`: If a Knowledge Base Article has a value and it is `en`(English) for the `language` attribute, then the user can view it
4. `entity.language == user.language`: If a Knowledge Base Article has a value other than `en` then it should match the user’s language to allow the user to view the article.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aisera.com/aisera-platform/adding-data-to-your-tenant/content-access-control/content-access-control-via-apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.