--- title: Push API usage example slug: '1336' canonical_url: https://docs.coveo.com/en/1336/ collection: index-content source_format: adoc --- # Push API usage example Assuming that you've [created a secured content Push source](https://docs.coveo.com/en/1546#content-security-tab), along with a [security identity provider for your secured Push source](https://docs.coveo.com/en/85/), you can then use the Push API to add a raw text [item](https://docs.coveo.com/en/210/) with access permissions to your [source](https://docs.coveo.com/en/246/). This article details the different components of a secured content Push source and sample requests to add a secured item and its associated security identities. ## Adding a secured item The following sample request adds a secured item to a [secured content Push source](https://docs.coveo.com/en/1779/) in the US East [deployment region](https://docs.coveo.com/en/2976#data-residency-configuration) using the [`Add or update an item`](https://docs.coveo.com/en/133/) HTTP request. ```http PUT https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/sources/mysourceidg3c5d1r2/documents?documentId=file%3A%2F%2Ffolder%2Fmytext.txt HTTP/1.1 ​ Content-Type: application/json Accept: application/json Authorization: Bearer **********-****-****-****-************ ``` Request body: ```json { "author": "Alice Smith", "date": "2017-11-08T12:18:41.666Z", "documenttype": "Text", "filename": "mytext.txt", "language": [ "English" ], "permanentid": "sample95829alice84720permanent93829id", "sourcetype": "Push", "title": "My Text", "fileExtension": ".txt", "data": "This is a sample text written by Alice Smith.", "permissions": [ { "allowAnonymous": false, "allowedPermissions": [ { "identity": "AlphaTeam", "identityType": "Group" } ], "deniedPermissions": [ { "identity": "bob@example.com", "identityType": "User" } ] } ] } ``` In the above example, several pieces of [metadata](https://docs.coveo.com/en/218/) are pushed along with the item (for example, `author`, `date`, and `documenttype`). This metadata will be [mapped](https://docs.coveo.com/en/217/) to the corresponding [fields](https://docs.coveo.com/en/200/) in the [index](https://docs.coveo.com/en/204/). For more details about the Push source metadata mapping process, see [About Push source item metadata](https://docs.coveo.com/en/115/). The `data` property contains the item body itself. Alternatively, you can [push the body of an item](https://docs.coveo.com/en/73/) in other ways, depending on your specific needs. Finally, the item has a set of [permissions](https://docs.coveo.com/en/107/). You must specify a [permission model](https://docs.coveo.com/en/225/) when adding an item to a secured Push source that doesn't have a global permission model in its configuration. In this example, all [security identities](https://docs.coveo.com/en/240/) that are members of the `AlphaTeam` [group](https://docs.coveo.com/en/202/) can access the item, except for [user](https://docs.coveo.com/en/250/) `bob@example.com`. ## Security identity definition You must [define the security identities](https://docs.coveo.com/en/42/) that an item permission model refers to, so that allowed users can access an item with access permissions in their [query](https://docs.coveo.com/en/231/) results. The following request [defines the `AlphaTeam` group](https://docs.coveo.com/en/42#defining-a-basic-group) in the security identity provider associated with the secured content Push source. ```http PUT https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/providers/mysecurityidentityprovider8d9s8d/permissions HTTP/1.1 ​ Content-Type: application/json Accept: application/json Authorization: Bearer **********-****-****-****-************ ``` Request body: ```json { "identity": { "name": "AlphaTeam", "type": "GROUP" }, "members": [ { "name": "alice@example.com", "type": "USER" }, { "name": "bob@example.com", "type": "USER" }, { "name": "david@example.com", "type": "USER" } ] } ``` See [`IdentityBody` model](https://docs.coveo.com/en/78#identitybody-model) for details. ## Security identity to Email Security Provider user mapping Currently, the group members (that is, `alice@example.com`, `bob@example.com`, and `david@example.com`) are not recognized by the provider. The recommended way to fix this issue is to create an [alias](https://docs.coveo.com/en/176/) relationship between each of those group members and the corresponding user in the [Email Security Provider](https://docs.coveo.com/en/87/). In addition to enabling your provider to detect those users, this will allow them to access content across many secured enterprise systems. The following request defines an alias for user `alice@example.com`. You should perform similar requests to define aliases for users `bob@example.com` and `david@example.com`. ```http PUT https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/providers/mysecurityidentityprovider8d9s8d/mappings HTTP/1.1 ​ Content-Type: application/json Accept: application/json Authorization: Bearer **********-****-****-****-************ ``` Request body: ```json { "Identity": { "Name": "alice@example.com", "Type": "USER" }, "Mappings": [ { "Name": "alice@example.com", "Type": "USER", "Provider": "Email Security Provider" } ] } ``` See [`MappedIdentityBody` model](https://docs.coveo.com/en/78#mappedidentitybody-model) for details. ## Validating the push requests After the [Push API processing delay](https://docs.coveo.com/en/32/), you can validate the success of your push requests by navigating to the [**Content Browser**](https://platform.cloud.coveo.com/admin/#/orgid/content/browser/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/content/browser/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/content/browser/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/content/browser/)) of the [Coveo Administration Console](https://docs.coveo.com/en/183/). The item should appear. ![Image of the item in the Content Browser | Coveo](https://docs.coveo.com/en/assets/images/index-content/example-item-in-content-browser.png) You can double-click the item to inspect its properties. In particular, you can validate the security identities. The image below shows that `alice@example.com` and `david@example.com` both have access to the item, while `bob@example.com` doesn't, as expected. Moreover, you can see that the alias relationships for `alice@example.com` and `david@example.com` are functional, the access being granted under `Email Security Provider` as well as under `mysecurityidentityprovider8d9s8d`. In contrast, `bob@example.com` is denied access in both providers. ![Permissions of the item in the Content Browser | Coveo](https://docs.coveo.com/en/assets/images/index-content/example-permissions.png) > **Note** > > A successful Push API response only confirms that the request was accepted for processing—it doesn't guarantee that the operation was completed successfully. > Failures can still occur downstream in the [Coveo indexing pipeline](https://docs.coveo.com/en/184/). > For example, an item may be rejected due to validation rules or unsupported content. > Many downstream failures can only be observed through the [**Log Browser**](https://platform.cloud.coveo.com/admin/#/orgid/logs/browser/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/logs/browser/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/logs/browser/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/logs/browser/)) in the [Coveo Administration Console](https://docs.coveo.com/en/183/). > > ![Log Browser showing permissions error | Coveo](:https://docs.coveo.com/en/assets/images/index-content/log-browser-example.png) > > For complete troubleshooting guidance, see the [Troubleshooting Push source issues](https://docs.coveo.com/en/95/) article. ## What's next? In this example, each item and security identity is pushed individually. However, the Push API also allows you to manage items and security identities in batches. A good way to learn about this feature is to do the [Push API tutorial](https://docs.coveo.com/en/161/). The [Push API tutorials](https://docs.coveo.com/en/161/) also introduce you to more advanced concepts, such as creating complex permission models.