---
title: User alias definition examples
slug: '46'
canonical_url: https://docs.coveo.com/en/46/
collection: index-content
source_format: adoc
---
# User alias definition examples
The Push API allows you to define [security identity relationships](https://docs.coveo.com/en/243/) between a [user](https://docs.coveo.com/en/250/) [security identity](https://docs.coveo.com/en/240/) and other user identities defined across multiple [security identity providers](https://docs.coveo.com/en/242/).
These _aliases_ indicate that all of the defined security identities correspond to the same person.

An [alias](https://docs.coveo.com/en/176/) definition must minimally contain:

* The name of the security identity for which you want to create an alias in the security identity provider of your secured push [source](https://docs.coveo.com/en/246/), as well as its entity type (normally `USER`).
* The name, entity type (normally `USER`), and security identity provider of each security identity with which to establish an alias relationship.

> **Notes**
>
> * The security identity for which you want to create an alias doesn't need to be defined in the security identity provider of your secured Push source.
> * The security identity provider of your secured Push source must be configured to [cascade](https://docs.coveo.com/en/3115/) to the security identity providers containing the security identities with which you want to establish an alias relationship.
>  
> If your security identity provider only cascades to a single security identity provider (for example, Email Security Provider), you don't need to specify a value for the `provider` property when creating an alias, as this cascading security identity provider will be used by default.

The alias definition may also contain the name and type (normally `GROUP` or `VIRTUAL_GROUP`) of each [granted identity](https://docs.coveo.com/en/201/) to assign to the alias.
For more information, see [`MappedIdentityBody` model](https://docs.coveo.com/en/78#mappedidentitybody-model).

> **Note**
>
> _Granted identities_ used to be called _well-known groups._
> To ensure backwards compatibility, the Push API still requires that you specify the granted identities of an alias in an array property whose name is `wellKnowns`.

> **Leading practice: Only define aliases between `USER` entities**
>
> Although you can establish alias relationships between any type of security identity, you should generally only define aliases between `USER` entities.

## Defining a single alias for a user

Assuming that the target security identity provider only cascades to the Email Security Provider, this establishes an alias relationship between the user `asmith` in the target security identity provider and the user `asmith@example.com` in the Email Security Provider.
This also assigns the `Everyone` granted identity to the alias.

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

## Defining many aliases for a user

This establishes an alias relationship between the user `bjones@example.com` in the target security identity provider and the users `bjones@example.com` and `bjones1@example.com` in the Email Security Provider, as well as the user `bob_jones` in `mysecurityidentityprovider`.
This implies that the target security identity provider is properly configured to cascade to both of these security identity providers.

```json
{
  "identity": {
    "name": "bjones@example.com",
    "type": "USER"
  },
  "mappings": [
    {
      "name": "bjones@example.com",
      "type": "USER",
      "provider": "Email Security Provider"
    },
    {
      "name": "bjones1@example.com",
      "type": "USER",
      "provider": "Email Security Provider"
    },
    {
      "name": "bob_jones",
      "type": "USER",
      "provider": "mysecurityidentityprovider"
    }
  ]
}
```