Add or update a single alias

In this article

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 (see Manage Batches of Security Identities).

Request template

PUT<MyOrganizationId>/providers/<MySecurityIdentityProviderId>/mappings HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <MyAccessToken>

Payload (see Security Identity Models - MappedIdentityBody)


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. In other words, if you’re Add or Update 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

Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************


  "identity": {
    "name": "",
    "type": "USER"
  "mappings": [
      "name": "",
      "type": "USER",
      "provider": "Email Security Provider"
  "wellKnowns": [
      "name": "Everyone",
      "type": "GROUP"

Successful response - 202 Accepted