---
title: Add or update a single security identity
slug: '167'
canonical_url: https://docs.coveo.com/en/167/
collection: index-content
source_format: adoc
---
# Add or update a single security identity
:figure-caption!:

The [permission model](https://docs.coveo.com/en/225/) of an [item](https://docs.coveo.com/en/210/) typically refers to one or several [security identities](https://docs.coveo.com/en/240/) which you can manage in the [security identity provider](https://docs.coveo.com/en/242/) of its secured Push [source](https://docs.coveo.com/en/246/).
Being able to add or update a single security identity can be useful, especially when you're testing the service, or to perform a very small [security identity update](https://docs.coveo.com/en/244/).

Use the `Add or update a security identity` request to push a security identity definition into a specific security identity provider.
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 security identities in a security identity provider.
Use [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>/permissions 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>/permissions 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>/permissions 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>/permissions 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 [your security identity provider ID](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 security identity you're pushing) must implement the [`IdentityBody` model](https://docs.coveo.com/en/78#identitybody-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 alias](https://docs.coveo.com/en/142/), 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](https://docs.coveo.com/en/1603/) for details.
> 
> 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 the `SampleGroup` security identity.

```http
PUT https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/providers/My%20Secured%20Push%20Source%20Security%20Identity%20Provider/permissions HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************
```

Request body:

```json
{
  "identity": {
    "name": "SampleGroup",
    "type": "GROUP"
  },
  "members": [
    {
      "name": "asmith@example.com",
      "type": "USER"
    },
    {
      "name": "SampleVirtualGroup",
      "type": "VIRTUAL_GROUP"
    }
  ],
  "wellKnowns": [
    {
      "name": "Domain Users",
      "type": "GROUP"
    }
  ]
}
```