Add or update a single alias

This is for:

In this article

Request template
Sample request

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 Push source that indexes the system permissions ("sourceVisibility": "SECURED") 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 (that is, perform a large-scale security identity update). If that’s what you need to do, you should use the batch operation instead.

Request template

Request definition

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>

Request body

See Security Identity Models - MappedIdentityBody.

{
  <MyAlias>
}

Note

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 ID of the target Coveo organization.
Replace <MySecurityIdentityProviderId> with the ID of the target security identity provider.

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 for details.

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

Replace <MyAlias> with the definition of the user alias you’re pushing.

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

Sample request

The following example shows how to add or update a single alias relationship and assigning a granted identity to this alias.

Request definition

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 **********-****-****-****-************

Request body

{
  "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