--- title: Manage batches of security identities slug: '55' canonical_url: https://docs.coveo.com/en/55/ collection: index-content source_format: adoc --- # Manage batches of security identities It's possible to add, update, and/or disable batches of [security identities](https://docs.coveo.com/en/240/) in the [security identity provider](https://docs.coveo.com/en/242/) of a secured Push [source](https://docs.coveo.com/en/246/). This means that you can update many security identities using only a few Push API requests, rather than performing numerous single security identity requests to achieve the same results. Therefore, managing security identities in batches is the best way to reduce the risk of getting throttled by the service. See [Push API limits - Security identity daily limits](https://docs.coveo.com/en/63#security-identity-daily-limits) for details. Performing batch security identity update requests is slightly more complex than performing single security identity requests, as doing so involves three distinct steps which are detailed in this article. ## Step 1: Create a file container See [Create a file container](https://docs.coveo.com/en/43/) for details. ## Step 2: Upload the security identity update into the file container Perform the following `PUT uploadUri` request to upload the security identity update into the Amazon S3 file container obtained in [step 1](#step-1-create-a-file-container). ### Request template ```http PUT HTTP/1.1 ​ ``` **Parameters**
Details * Replace `` with the value of the `uploadUri` property you got in the response when you created your file container in [step 1](#step-1-create-a-file-container). * Replace `` with the key-value pairs of the `requiredHeaders` object property you got in the response when you created your file container in [step 1](#step-1-create-a-file-container).
Request body: ```json { "members": [ * ], "mappings": [ * ], "deleted": [ { "identity": { "name": , "type": <"GROUP"|"UNKNOWN"|"USER"|"VIRTUAL_GROUP"> } }* ] } ``` **Parameters**
Details The request body must implement the [`BatchIdentityBody` model](https://docs.coveo.com/en/78#batchidentitybody-model). In the `members` array: * Replace `*` with any number of [security identity definitions](https://docs.coveo.com/en/42/) to add or update in the target security identity provider. [IMPORTANT]
When pushing a [group](https://docs.coveo.com/en/202/), you overwrite the current version of that group. Therefore, to keep existing group members, be sure to include them in the new group configuration. If this isn't viable, consider using [granted security identities](https://docs.coveo.com/en/1603#granted-security-identities) instead. #### In the `mappings` array: * Replace `*` with any number of [user alias definitions](https://docs.coveo.com/en/46/) to add or update in the target security identity provider. In the `deleted` array: * Replace `` by the name of the security identity to disable for each security identity you include. * Replace `<"GROUP"|"UNKNOWN"|"USER"|"VIRTUAL_GROUP">` by the corresponding entity type. > **Important** > > Make consistent use of the `wellKnowns` parameter among different push API calls. > In other words, for any API request which sets `wellKnowns`, like [Add or update a single security identity](https://docs.coveo.com/en/167/) or [Add or update a single alias](https://docs.coveo.com/en/142/), make sure that the same `wellKnowns` are also sent when using that call to prevent involuntary disassociation of granted identities from their groups. > See [Group and granted security identities](https://docs.coveo.com/en/1603/) for details. ##### Successful response: `200 OK` A successful response has no content, but indicates that the [security identity update](https://docs.coveo.com/en/244/) was successfully uploaded into the Amazon S3 file container. ### Sample request The following example shows how to upload a batch of security identity updates into a file container. ```http PUT link:https://coveo-nprod-customerdata.s3.amazonaws.com/proda/blobstore/mycoveocloudv2organizationg8tp8wu3/b5e8767e-8f0d-4a89-9095-1127915c89c7[...] HTTP/1.1 ​ x-amz-server-side-encryption: AES256 Content-Type: application/octet-stream ``` Request body: ```json { "members": [ { "identity": { "name": "SampleGroup", "type": "GROUP" }, "members": [ { "name": "asmith@example.com", "type": "USER" }, // ...More members for this group... ], "wellKnowns": [ { "name": "Domain Users", "type": "GROUP" }, // ...More granted identities for this group... ] }, // ...More security identity definitions... ], "mappings": [ { "identity": { "name": "asmith@example.com", "type": "USER" }, "mappings": [ { "name": "alice_smith@example.com", "type": "USER", "provider": "Email Security Provider" }, // ...More aliases for this user... ], "wellKnowns": [ { "name": "Everyone", "type": "GROUP" }, // ...More granted identities for this alias... ] }, // ...More alias definitions... ], "deleted": [ { "identity": { "name": "SampleGroup2", "type": "GROUP" } }, { "identity": { "name": "bjones_alias", "type": "USER" } } // ...More security identities to disable... ] } ``` ## Step 3: Push the file container into a security identity provider Use the `Add, update, and/or delete a batch of security identities` request to push the Amazon S3 file container into the security identity provider of your secured Push source. ### Request template **US East region** [%collapsible%open] #### [source,http,subs=attributes] ``` PUT https://api.cloud.coveo.com/push/v1/organizations//providers//permissions/batch?fileId= HTTP/1.1 ​ Accept: application/json Authorization: Bearer ``` #### .Canada region
Details [source,http,subs=attributes] ``` PUT https://api-ca.cloud.coveo.com/push/v1/organizations//providers//permissions/batch?fileId= HTTP/1.1 ​ Accept: application/json Authorization: Bearer ```
**Ireland region**
Details [source,http,subs=attributes] ``` PUT https://api-eu.cloud.coveo.com/push/v1/organizations//providers//permissions/batch?fileId= HTTP/1.1 ​ Accept: application/json Authorization: Bearer ```
**Australia region**
Details [source,http,subs=attributes] ``` PUT https://api-au.cloud.coveo.com/push/v1/organizations//providers//permissions/batch?fileId= HTTP/1.1 ​ Accept: application/json Authorization: Bearer ```
Request parameters: **Parameters**
Details In the request path: * Replace `` with your [organization ID](https://docs.coveo.com/en/148/). * Replace `` by the actual ID of the target security identity provider. See [Create a security identity provider for a secured push source](https://docs.coveo.com/en/85/) for details. In the query string: * Replace `` by the `filedId` you got from [step 1](#step-1-create-a-file-container). In the `Authorization` HTTP header: * Replace `` with a Push source API key that grants the [set of privileges required to push security identities](https://docs.coveo.com/en/1546#api-key) to the security identity provider.
Request body: None You may notice that certain [security identities](https://docs.coveo.com/en/240/) in a security identity provider are _in error._ Typically, this is because the security identity no longer exists in the security identity provider (that is, it has been disabled), but one or several [item](https://docs.coveo.com/en/210/) [permission models](https://docs.coveo.com/en/225/) still refer to it. To address this error, perform the necessary push requests on the secured Push source to ensure that item permission models and security identities are perfectly in sync. > **Tip** > > The contents of a file container can be pushed to multiple security identity providers or sources in the same [Coveo organization](https://docs.coveo.com/en/185/). > Just update the target `providerId`/`sourceId` and Authorization HTTP header access token in your other security identity or [item batch requests](https://docs.coveo.com/en/90#step-3-push-the-file-container-into-a-push-source). > > The file container remains available for 4 days. ### Sample request This example shows how to push a file container into the security identity provider of a secured Push source. ```http PUT https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/providers/My%20Secured%20Push%20Source%20Security%20Identity%20Provider/permissions/batch?fileId=b5e8767e-8f0d-4a89-9095-1127915c89c7 HTTP/1.1 ​ Accept: application/json Authorization: Bearer **********-****-****-****-************ ```