---
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.md) is a [security identity relationship](https://docs.coveo.com/en/243.md) typically defined between two [user](https://docs.coveo.com/en/250.md) entities across different [security identity providers](https://docs.coveo.com/en/242.md) 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.md) that indexes the system permissions (`"sourceVisibility": "SECURED"`) by defining a [security identity](https://docs.coveo.com/en/240.md) 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 [Push API quotas and constraints](https://docs.coveo.com/en/63.md), 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.md) 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.md), not item [permissions](https://docs.coveo.com/en/223.md).
## Request template

> **Note**
>
> The Push API still uses region-specific endpoints.
> Use the endpoint that matches the primary deployment region of your Coveo organization.
**US East region**
<details><summary>Details</summary>

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

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

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

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

```http
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>
**HIPAA region**
<details><summary>Details</summary>

```http
PUT https://apihipaa.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.md).

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

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.md#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.md#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.md), 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.md) 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"
    }
  ]
}
```