---
title: Add or update a single alias
slug: '142'
canonical_url: https://docs.coveo.com/en/142/
collection: index-content
source_format: adoc
---
# Add or update a single alias
An [alias](https://docs.coveo.com/en/176/) is a [security identity relationship](https://docs.coveo.com/en/243/) typically defined between two [user](https://docs.coveo.com/en/250/) entities across different [security identity providers](https://docs.coveo.com/en/242/) 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](https://docs.coveo.com/en/246/) that indexes the system permissions (`"sourceVisibility": "SECURED"`) by defining a [security identity](https://docs.coveo.com/en/240/) 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](https://docs.coveo.com/en/63/), 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](https://docs.coveo.com/en/55/) 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](https://docs.coveo.com/en/240/), not item [permissions](https://docs.coveo.com/en/223/).

## Request template

**US East region**
[%collapsible%open]
#### [source,http,subs=attributes]
```
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
<details><summary>Details</summary>

[source,http,subs=attributes]
```
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>
```

</details>

**Ireland region**
<details><summary>Details</summary>

[source,http,subs=attributes]
```
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>
```

</details>

**Australia region**
<details><summary>Details</summary>

[source,http,subs=attributes]
```
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>
```

</details>

Request parameters:

**Parameters**
<details><summary>Details</summary>

In the request path:

* Replace `<MyOrganizationId>` with your [organization ID](https://docs.coveo.com/en/148/).

* Replace `<MySecurityIdentityProviderId>` with the [ID of the target security identity provider](https://docs.coveo.com/en/85/).

In the `Authorization` HTTP header:

* Replace `<MyAccessToken>` with a Push source API key that grants the [set of privileges required to push security identities](https://docs.coveo.com/en/1546#api-key) to the security identity provider.

</details>

Request body:

The request body (that is, the definition of the user alias you're pushing) must implement the [`MappedIdentityBody` model](https://docs.coveo.com/en/78#mappedidentitybody-model).

> **Important**
>
> 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](https://docs.coveo.com/en/167/), make sure that the same `wellKnowns` are also sent when using that call to prevent involuntary disassociation of [granted identities](https://docs.coveo.com/en/1603/) from their groups.
> 
> This also applies to the repeated use of any given API call.

Successful response: `202 Accepted`

## Sample request

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

```http
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:

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