---
title: 'Push API tutorial 2: Manage secured content'
slug: '98'
canonical_url: https://docs.coveo.com/en/98/
collection: index-content
source_format: adoc
---
# Push API tutorial 2: Manage secured content
In the [previous tutorial](https://docs.coveo.com/en/92/), you created a public Push [source](https://docs.coveo.com/en/246/) in which you added, and then deleted, a simple [item](https://docs.coveo.com/en/210/).

In this tutorial, you'll configure your Push source to make it secure and create its associated [security identity provider](https://docs.coveo.com/en/242/).
You'll then perform a small mock content update, followed by a small mock [security identity update](https://docs.coveo.com/en/244/).

> **Note**
>
> This tutorial assumes that the permissions in the fictional content repository are entirely determined at the item level.

## Prerequisites

You need the setup described in the [Push API Tutorials](https://docs.coveo.com/en/161#tutorial-setup) article.

## Step 1: Secure your Push source content

With a secured content Push source, you can manage items with [permission models](https://docs.coveo.com/en/225/).
The [index](https://docs.coveo.com/en/204/) uses a [permission model](https://docs.coveo.com/en/1719/) to [determine whether a user can see](https://docs.coveo.com/en/1749#basic-search-flowchart) a given item in their [query](https://docs.coveo.com/en/231/) results.

. Access the [**Sources**](https://platform.cloud.coveo.com/admin/#/orgid/content/sources/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/content/sources/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/content/sources/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/content/sources/)) page in the [Coveo Administration Console](https://docs.coveo.com/en/183/).

. Click your Push source, and then click **Edit** in the Action bar.

. On the **Edit a Push source** page, select the **Content security** tab.

. Select [**Same users and groups as in your current permission system**](https://docs.coveo.com/en/1779/).

. Click **Save**.

## Step 2: Create a security identity provider

The security identity provider of a secured source is a Coveo organization module whose main purpose is to crawl a specific secured enterprise system on a regular basis to retrieve its latest [security identity relationships](https://docs.coveo.com/en/243/) and forward this data to the [security identity cache](https://docs.coveo.com/en/241/).
For more information, see [Security identity cache and provider](https://docs.coveo.com/en/1527/).
A security identity provider allows the items in a secured source to reference existing and valid [security identities](https://docs.coveo.com/en/240/) in their permission models.
This ensures that only the [users](https://docs.coveo.com/en/250/) who are allowed to see a specific item in its original secured repository can see this item in their query results.
See [Typical Coveo secured search](https://docs.coveo.com/en/1863/) for more details.

You need to use the Security Cache API [`Create a security provider for an organization`](https://docs.coveo.com/en/85/) HTTP request to create the security identity provider.

> **Note**
>
> The Security Cache API [`Create a security provider for an organization`](https://docs.coveo.com/en/85/) HTTP request requires the **Edit** access level on the [**Security identities**](https://docs.coveo.com/en/1707#security-identity-providers-domain) domain, which isn't granted by an API key created specifically for a Push source.

To create the security identity provider

. Click the relevant link to open the Security Cache API Swagger UI `Create a security provider for an organization` HTTP request page associated with your Coveo organization region:

** [US organizations](https://platform.cloud.coveo.com/docs/?urls.primaryName=SecurityCache#/Security%20Providers/rest_organizations_paramId_securityproviders_post)

** [EU organizations](https://platform-eu.cloud.coveo.com/docs/?urls.primaryName=SecurityCache#/Security%20Providers/rest_organizations_paramId_securityproviders_post)

** [CA organizations](https://platform-ca.cloud.coveo.com/docs/?urls.primaryName=SecurityCache#/Security%20Providers/rest_organizations_paramId_securityproviders_post)

** [AU organizations](https://platform-au.cloud.coveo.com/docs/?urls.primaryName=SecurityCache#/Security%20Providers/rest_organizations_paramId_securityproviders_post)

. Click **Authorize** in the upper-right corner of the page, and then log in to the [Coveo Platform](https://docs.coveo.com/en/186/) using your Coveo organization administrator account.

. In the `Create a security provider for an organization` HTTP request section, click **Try it out**.

. Under **Parameters**, set the **organizationId** value to [your Coveo organization ID](https://docs.coveo.com/en/161#tutorial-setup).

. Under **Request body**, paste the following:

```json
{
  "id" : "Push API Tutorial Security Identity Provider",
  "displayName" : "Push API Tutorial Security Identity Provider",
  "nodeRequired": false,
  "type": "EXPANDED",
  "referencedBy": [
    {
      "id": "<SOURCE_ID>", <1>
      "type": "SOURCE"
    }
  ],
  "cascadingSecurityProviders": {
      "Email Security Provider": {
        "id": "Email Security Provider",
        "type": "EMAIL"
    }
  }
}
```
<1> Replace `<SOURCE_ID>` with the [ID](https://docs.coveo.com/en/3390#copy-a-source-name-or-id) of your secured Push source.

. Click **Execute**.

You should receive a `200 OK` response, and the **Response body** section should contain information about the newly created security identity provider.

> **Note**
>
> Initially, your security identity provider has no means of automatically crawling its intended target secured content repository.
> You must eventually implement this behavior with your own code, but that's beyond the scope of this tutorial.

## Step 3: Add items to your source

You'll now send three Push API requests to add items to your Push source, using the [`Add or update an item`](https://docs.coveo.com/en/133#add-or-update-a-complex-secured-item) request each time.

. In your HTTP client, create a new PUT request using the Push API endpoint corresponding to your deployment region.

--
**US East region**
[%collapsible%open]
#### [source,http,subs=attributes]
```
DELETE https://api.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/olderthan?orderingId={orderingId} HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer {accessToken}
```
#### .Canada region
<details><summary>Details</summary>

[source,http,subs=attributes]
```
DELETE https://api-ca.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/olderthan?orderingId={orderingId} HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer {accessToken}
```

</details>

**Ireland region**
<details><summary>Details</summary>

[source,http,subs=attributes]
```
DELETE https://api-eu.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/olderthan?orderingId={orderingId} HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer {accessToken}
```

</details>

**Australia region**
<details><summary>Details</summary>

[source,http,subs=attributes]
```
DELETE https://api-au.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/olderthan?orderingId={orderingId} HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer {accessToken}
```

</details>

--

. Configure the first HTTP request.


<div class="admonitionblock">
<table>
<tbody><tr>
<td class="icon">
<img src="{{ site.baseurl }}/assets/icons/postman.svg" alt="Postman" data-ot-ignore="">
</td>
<td class="content">
<div class="paragraph">
<p>In the <a href="{{ site.baseurl }}/161/#recommended-the-coveo-push-api-tutorials-postman-collection">Coveo Push API Tutorials collection</a>, all the necessary variables and payload have already been set for the three requests.</p>
</div>
</td>
</tr>
</tbody></table>
</div>

** Set the `organizationId` and `sourceId` path parameters to the values you noted in the [Push API Tutorials setup](https://docs.coveo.com/en/161#tutorial-setup) article.
** Use your API key as the `Authorization` header `accessToken` value.

** Set the `documentId` query parameter value to `+file://folder/+`.
This URI doesn't exist, but that doesn't matter as you're only pushing dummy items for this tutorial.

** Use the following JSON as your request body.
Its `permissions` property indicates that any anonymous user can see the item in their query results.

```json
 {
   "data": "",
   "permissions": [
     {
       "allowAnonymous": true
     }
   ]
 }
```

. Send the request.
You should receive a `202` response.

. For the second request, use the same endpoint and headers as in the first request.
Complete the request configuration as follows:

** Set the `documentId` query parameter value to `+file://folder/item1.txt+`.

** Use the following JSON as your request body.
Its `permissions` property indicates that only users `asmith@example.com` and `bjones@example.com` can see the item in their query results.
You'll define these security identities in [step 4](#step-4-add-security-identities-to-your-security-identity-provider).

```json
 {
   "data": "Item 1 raw textual data",
   "permissions": [
     {
       "allowAnonymous": false,
       "allowedPermissions": [
         {
           "identity": "asmith@example.com",
           "identityType": "User"
         },
         {
           "identity": "bjones@example.com",
           "identityType": "User"
         }
       ]
     }
   ]
 }
```

. Send the request.

. For the third request, use the same endpoint and headers as in the previous requests.
Complete the request configuration as follows:

** Set the `documentId` query parameter value to `+file://folder/item2.txt+`.

** Use the following JSON as your request body.
Its `permissions` property indicates that only the user `asmith@example.com` can see this item in their query results.
Because `bjones@example.com` is listed in both allowed and denied permissions, this user [is effectively denied access](https://docs.coveo.com/en/1863/) to the item in their query results.

```json
 {
   "data": "Item 2 raw textual data",
   "permissions": [
     {
       "allowAnonymous": false,
       "allowedPermissions": [
         {
           "identity": "asmith@example.com",
           "identityType": "User"
         },
         {
           "identity": "bjones@example.com",
           "identityType": "User"
         }
       ],
       "deniedPermissions": [
         {
           "identity": "bjones@example.com",
           "identityType": "User"
         }
       ]
     }
   ]
 }
```

. Send the request.

You may have to [wait several minutes](https://docs.coveo.com/en/32/) before these three items become available in your source.

> **Note**
>
> You'll learn how to push batches of items in [Tutorial 3](https://docs.coveo.com/en/54/).
> This tutorial also covers how to include metadata and complex permission models.

## Step 4: Add security identities to your security identity provider

The permission models of the second and third items you pushed in [step 3](#step-3-add-items-to-your-source) reference two security identities: `asmith@example.com` and `bjones@example.com`.
However, these security identities haven't been defined in the security identity provider you created in [step 2](#step-2-create-a-security-identity-provider).
As a result, after the [Coveo indexing pipeline](https://docs.coveo.com/en/184/) processes these items, the unknown security identities will cause errors.
The users won't be able to see the items in their query results.

To fix this, you'll now add the `asmith@example.com` and `bjones@example.com` security identities to the security identity provider using an [`Add or update a security identity`](https://docs.coveo.com/en/167/) request for each.

. In your HTTP client, create a new PUT request using the Push API endpoint corresponding to your deployment region.

--
**US East region**
[%collapsible%open]
#### [source,http,subs=attributes]
```
DELETE https://api.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/olderthan?orderingId={orderingId} HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer {accessToken}
```
#### .Canada region
<details><summary>Details</summary>

[source,http,subs=attributes]
```
DELETE https://api-ca.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/olderthan?orderingId={orderingId} HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer {accessToken}
```

</details>

**Ireland region**
<details><summary>Details</summary>

[source,http,subs=attributes]
```
DELETE https://api-eu.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/olderthan?orderingId={orderingId} HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer {accessToken}
```

</details>

**Australia region**
<details><summary>Details</summary>

[source,http,subs=attributes]
```
DELETE https://api-au.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/olderthan?orderingId={orderingId} HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer {accessToken}
```

</details>

--

. Configure the request.


<div class="admonitionblock">
<table>
<tbody><tr>
<td class="icon">
<img src="{{ site.baseurl }}/assets/icons/postman.svg" alt="Postman" data-ot-ignore="">
</td>
<td class="content">
<div class="paragraph">
<p>The <a href="{{ site.baseurl }}/161/#recommended-the-coveo-push-api-tutorials-postman-collection">Coveo Push API Tutorials collection</a> comes with the <strong>securityIdentityProviderId</strong> variable set to the <code>id</code> value specified in the body of the <a href="#step-2-create-a-security-identity-provider">security identity provider creation</a> request performed earlier.
All the necessary variables and payload have already been set for this request.</p>
</div>
</td>
</tr>
</tbody></table>
</div>

** Set the `organizationId` and `providerId` path parameter values.
The `providerId` value should be `Push API Tutorial Security Identity Provider`, that is, the `id` value in the body of the [security identity provider creation](#step-2-create-a-security-identity-provider) request performed earlier.

** Use your API key as the `Authorization` header `accessToken` value.

** Use the following JSON as your request body to define the `asmith@example.com` user security identity.

```json
 {
   "identity": {
     "name": "asmith@example.com",
     "type": "USER"
   }
 }
```

. Send the request.

. For the second request, use the same endpoint and headers as in the previous request.

. Use the following JSON as your request body to define the `bjones@example.com` user security identity.

```json
 {
   "identity": {
     "name": "bjones@example.com",
     "type": "USER"
   }
 }
```

. Send the request.

You should receive a `202` response for both requests.

> **Note**
>
> You'll learn how to define batches of security identities including [aliases](https://docs.coveo.com/en/176/), [groups](https://docs.coveo.com/en/202/), and [granted identities](https://docs.coveo.com/en/201/) in the [next tutorial](https://docs.coveo.com/en/54/).

## Step 5: Validate the indexing status of the items

As a reminder, the table below summarizes the information and effective permissions on the items you pushed in [step 3](#step-3-add-items-to-your-source).

[%header,cols="1,1,1"]
|===
|`documentId`
|`data`
|`permissions`

|+file://folder/+
|""
|Anonymous [check]

|+file://folder/item1.txt+
|"Item 1 raw textual data"
a|Anonymous [x]  
+asmith@example.com+ [check]  
+bjones@example.com+ [check]

|+file://folder/item2.txt+
|"Item 2 raw textual data"
a|Anonymous [x]  
+asmith@example.com+ [check]  
+bjones@example.com+ [x]
|===

The [Coveo Administration Console](https://docs.coveo.com/en/183/) **Content Browser** is a powerful tool that lets you emulate the query results that security identities would see in a [search interface](https://docs.coveo.com/en/2741/).
You'll now use the **Content Browser** to validate the successful indexing of the three items, both in terms of their content and permissions.

. Access the [**Sources**](https://platform.cloud.coveo.com/admin/#/orgid/content/sources/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/content/sources/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/content/sources/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/content/sources/)) page.

. On the Push source row, click **Open in Content Browser**.

![Show source items in the Content Browser](https://docs.coveo.com/en/assets/images/index-content/open-in-content-browser.png)

Note that with the **View all content** option enabled in the **Content Browser**, you can see all items in the results.

![The Content Browser View all content option | Coveo](https://docs.coveo.com/en/assets/images/index-content/view-all-content.png)

As a [Coveo organization](https://docs.coveo.com/en/185/) administrator, you have the `Allowed` access level on the [`View all content`](https://docs.coveo.com/en/1707#view-all-content-domain) domain and the privilege to bypass item permission models.

. On the [**Security Identities**](https://platform.cloud.coveo.com/admin/#/orgid/content/permissions/providers/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/content/permissions/providers/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/content/permissions/providers/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/content/permissions/providers/)) page, click your Push API security identity provider, and then click **Browse identities** in the Action bar.

. Click `+bjones@example.com+`, and then click **Search as** in the Action bar.

You're now impersonating `+bjones@example.com+` and seeing the two items that this user would see in a [search interface](https://docs.coveo.com/en/2741/).

![Searching as bjones in the Content Browser | Coveo](https://docs.coveo.com/en/assets/images/index-content/search-as-b-jones.png)

You can repeat the last steps to validate that `+asmith@example.com+` can see all three items.

## Step 6: Delete the items

To begin the next tutorial with a clean source, you'll now send a [`Delete an item and optionally its children`](https://docs.coveo.com/en/171/) request to delete the three items you added in this tutorial.

. In your HTTP client, create a new DELETE request using the Push API endpoint corresponding to your deployment region.

--

**US East region**
[%collapsible%open]
#### [source,http,subs=attributes]
```
DELETE https://api.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/olderthan?orderingId={orderingId} HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}
```
#### .Canada region
<details><summary>Details</summary>

[source,http,subs=attributes]
```
DELETE https://api-ca.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/olderthan?orderingId={orderingId} HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}
```

</details>

**Ireland region**
<details><summary>Details</summary>

[source,http,subs=attributes]
```
DELETE https://api-eu.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/olderthan?orderingId={orderingId} HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}
```

</details>

**Australia region**
<details><summary>Details</summary>

[source,http,subs=attributes]
```
DELETE https://api-au.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/olderthan?orderingId={orderingId} HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}
```

</details>
--

. Configure the request.


<div class="admonitionblock">
<table>
<tbody><tr>
<td class="icon">
<img src="{{ site.baseurl }}/assets/icons/postman.svg" alt="Postman" data-ot-ignore="">
</td>
<td class="content">
<div class="paragraph">
<p>In the <a href="{{ site.baseurl }}/161/#recommended-the-coveo-push-api-tutorials-postman-collection">Coveo Push API Tutorials collection</a>, all the necessary variables have already been set for this request.</p>
</div>
</td>
</tr>
</tbody></table>
</div>

** Set the `organizationId` and `sourceId` path parameter values.

** Use your API key as the `Authorization` header `accessToken` value.

** Set the `documentId` query parameter to `+file://folder/+` and the `deleteChildren` query parameter to `true`.
This deletes the item whose `documentId` is the one you specified and all items whose `documentId` values are nested under the `documentId` of the parent.
In this case, the `+file://folder+` item and all other items matching `+file://folder/*+` in the target source will be deleted.

. Send the request.

You should receive a `202` response.
Shortly after, the [**Sources**](https://platform.cloud.coveo.com/admin/#/orgid/content/sources/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/content/sources/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/content/sources/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/content/sources/)) page should show your Push source with `No items` in the **Content** column.

## Step 7: Disable the security identities

By default, when you perform a Push API request that includes the optional [`orderingId` parameter](https://docs.coveo.com/en/147/), the service automatically sets `orderingId` to the current number of milliseconds since the Unix epoch.
Each individual Push API request receives its own timestamp value.
The item `orderingid` field value, which you see when [inspecting the item](https://docs.coveo.com/en/2053#inspect-search-results) in the **Content Browser**, reflects the timestamp of the last Push API request that modified it.

You can compare the mandatory `orderingId` parameter value used in a [`Delete old items`](https://docs.coveo.com/en/131/) or [`Delete old security identities`](https://docs.coveo.com/en/33/) HTTP request to the optional `orderingId` parameter value used in other Push API HTTP requests.

To begin the next tutorial with a clean security identity provider, you'll now disable the security identities using the [`Delete old security identities`](https://docs.coveo.com/en/33/) request.

. In your HTTP client, create a new DELETE request using the Push API endpoint corresponding to your deployment region.

--

**US East region**
[%collapsible%open]
#### [source,http,subs=attributes]
```
DELETE https://api.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/olderthan?orderingId={orderingId} HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}
```
#### .Canada region
<details><summary>Details</summary>

[source,http,subs=attributes]
```
DELETE https://api-ca.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/olderthan?orderingId={orderingId} HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}
```

</details>

**Ireland region**
<details><summary>Details</summary>

[source,http,subs=attributes]
```
DELETE https://api-eu.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/olderthan?orderingId={orderingId} HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}
```

</details>

**Australia region**
<details><summary>Details</summary>

[source,http,subs=attributes]
```
DELETE https://api-au.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/olderthan?orderingId={orderingId} HTTP/1.1
​
Accept: application/json
Authorization: Bearer {accessToken}
```

</details>
--

. Configure the request.


<div class="admonitionblock">
<table>
<tbody><tr>
<td class="icon">
<img src="{{ site.baseurl }}/assets/icons/postman.svg" alt="Postman" data-ot-ignore="">
</td>
<td class="content">
<div class="paragraph">
<p>You need to set the <a href="{{ site.baseurl }}/161/#recommended-the-coveo-push-api-tutorials-postman-collection">Coveo Push API Tutorials collection</a> <strong>orderingId</strong> variable value to the 13-digit current number of milliseconds since the Unix epoch.</p>
</div>
</td>
</tr>
</tbody></table>
</div>

** Set the `organizationId` and `providerId` path parameters.
The `providerId` value should be `Push API Tutorial Security Identity Provider`, that is, the `id` value in the body of the [security identity provider creation](#step-2-create-a-security-identity-provider) request performed earlier.

** Use your API key as the `Authorization` header `accessToken` value.

** Set the `orderingId` query parameter value.
Use the 13-digit current number of milliseconds since the Unix epoch.
You can get it from [https://currentmillis.com/](https://currentmillis.com/).

. Send the request.

Afterward, [refresh your security identity provider](https://docs.coveo.com/en/1905#refresh-all-security-identities).

## What's next?

Proceed to [Push API tutorial 3: Using batch updates to manage complex secured content](https://docs.coveo.com/en/54/).