Add or Update a Single Security Identity

In this article

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:

In the Authorization HTTP header:

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

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