Adding or Updating a Single Alias

An alias is a security identity relationship typically defined between two user entities across different security identity providers to indicate that these entities both correspond to the same person in distinct secured enterprise system. You can manage aliases in the security identity provider of a secured Push source by defining a security identity with a mappings array.

Use the Add or update an alias operation to create or modify a user alias.

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

Request template

PUT https://api.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/providers/<MySecurityIdentityProviderId>/mappings HTTP/1.1
 
Content-Type: application/json
Accept: application/json
Authorization: Bearer <MyAccessToken>

Payload (see Security Identity Models - MappedIdentityBody)

{
  <MyAlias>
}

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 - MappedIdentityBody):

You must make consistent use of the wellKnowns parameter across different push API calls. That is, if you are Adding or Updating a Single Security Identity, 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 a single alias relationship and assigning a granted identity to this alias

PUT https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/providers/My%20Secured%20Push%20Source%20Security%20Identity%20Provider/mappings HTTP/1.1
 
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "identity": {
    "name": "asmith@example.com",
    "type": "USER"
  },
  "mappings": [
    {
      "name": "asmith@example.com",
      "type": "USER",
      "provider": "Email Security Provider"
    }
  ],
  "wellKnowns": [
    {
      "name": "Everyone",
      "type": "GROUP"
    }
  ]
}

Successful response - 202 Accepted

null
Recommended Articles