Add or Update a Single Security Identity

This is for:

In this article

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 when you need to perform a very small security identity update.

Use the Add or update a security identity operation to push a security identity definition into a specific security identity provider.

You should never use this operation repetitively to add or update many security identities in security identity provider (that is, perform a large scale security identity update). If that’s what you need to do, you should use the batch operation instead (see Manage Batches of Security Identities).

Request template

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>

Payload (see Security Identity Models - IdentityBody)

{
  <MySecurityIdentity>
}

For legacy reasons, the request path of this operation uses the word permissions instead of identities. While those two concepts are related, they have entirely different meanings.

Remember that this operation actually allows you to interact with security identities (not item permissions).

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 an access token that grants the Organization - View and Security identity providers - View/Edit privileges in the target Coveo organization (see Create an API key, Get the privileges of an access token, and Get your Coveo access token).

In the request body (see Security Identity Models - IdentityBody):

Replace <MySecurityIdentity> with the actual definition of the security identity you’re pushing (see Security Identity Definition Examples).

You must make consistent use of the wellKnowns parameter among different push API calls. In other words, if you’re Add or Update 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). This also applies to the repeated use of any given API call.

Sample Request

Adding (or updating) 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 **********-****-****-****-************

Payload

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

Successful response - 202 Accepted

null