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 request to create or modify a user alias. To maximize efficiency and comply with API consumption limits, don’t use this request repeatedly to add or update many aliases in a security identity provider. If that’s what you need to do, use the 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>/mappings 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>/mappings 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>/mappings 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>/mappings HTTP/1.1

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

Request parameters:

Parameters

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 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 user alias you’re pushing) must implement the MappedIdentityBody model.

Make consistent use of the wellKnowns parameter among 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.

Successful response: 202 Accepted

null

Sample request

The following example shows how to add or update a single alias relationship, and assign 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 **********-****-****-****-************

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"
    }
  ]
}