Add or update a single security identity

This is for:

In this article

Request template
Sample request

The permission model of an item typically refers to one or several security identities which you can manage in the security identity provider of its secured Push source. Being able to add or update a single security identity can be useful, especially when you’re testing the service, or to perform a very small security identity update.

Use the Add or update a security identity request to push a security identity definition into a specific security identity provider. To maximize efficiency and comply with API consumption limits, don’t use this request repeatedly to add or update many security identities in a security identity provider. Use batch update requests instead.

Note

For legacy reasons, the path of this request uses the word permissions instead of identities. While those two concepts are related, they have entirely different meanings. Remember that this request actually allows you to interact with security identities, not item permissions.

Request template

US East region

PUT https://api.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/providers/<MySecurityIdentityProviderId>/permissions HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer <MyAccessToken>

Canada region

PUT https://api-ca.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/providers/<MySecurityIdentityProviderId>/permissions HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer <MyAccessToken>

Ireland region

PUT https://api-eu.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/providers/<MySecurityIdentityProviderId>/permissions HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer <MyAccessToken>

Australia region

PUT https://api-au.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/providers/<MySecurityIdentityProviderId>/permissions HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer <MyAccessToken>

Request parameters:

Parameters

In the request path:

Replace <MyOrganizationId> with the actual ID of the target Coveo organization (see Retrieving the ID of a Coveo organization).
Replace <MySecurityIdentityProviderId> with the actual ID of the target security identity provider (see Create a security identity provider for a secured Push source).

In the Authorization HTTP header:

Replace <MyAccessToken> with a Push source API key that grants the set of privileges required to push security identities to the security identity provider.

Request body:

The request body (that is, the definition of the security identity you’re pushing) must implement the IdentityBody model.

Make consistent use of the wellKnowns parameter among different push API calls. In other words, if you’re adding or updating a single alias, 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 for details.

This also applies to the repeated use of any given API call.

Successful response: 202 Accepted

null

Sample request

The following example shows how to add or update the SampleGroup security identity.

PUT https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/providers/My%20Secured%20Push%20Source%20Security%20Identity%20Provider/permissions HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Request body:

{
  "identity": {
    "name": "SampleGroup",
    "type": "GROUP"
  },
  "members": [
    {
      "name": "asmith@example.com",
      "type": "USER"
    },
    {
      "name": "SampleVirtualGroup",
      "type": "VIRTUAL_GROUP"
    }
  ],
  "wellKnowns": [
    {
      "name": "Domain Users",
      "type": "GROUP"
    }
  ]
}