---
title: "POST | Add access policies to a user group by [id]"
slug: "api-v2-post-add-user-group-access-policies"
updated: 2026-11-06T19:01:15Z
published: 2026-11-06T19:01:15Z
canonical: "docs.senhasegura.io/api-v2-post-add-user-group-access-policies"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.senhasegura.io/llms.txt
> Use this file to discover all available pages before exploring further.

# POST | Add access policies to a user group by [id]

## Description

Bind one or more access policies to a user group. Each binding carries the access policy, the profile it grants to the members of the group, and its approval level.

The request is idempotent. When an active binding to the same access policy already exists, the platform updates it in place instead of creating a second one, so a request that changes only the profile or the level can be sent against an existing binding.

The application can bind only PAM access policies released to its authorization in A2A. The rule also applies to an authorization with **Super admin** enabled. Any other access policy gets the same answer as one that does not exist, so the response never reveals whether it exists.

A request that names any access policy outside this scope saves nothing, even when its other bindings are valid. If the application has no active authorization in A2A, it cannot bind any access policy.

---

## Prerequisites

- An application with the **Users** authorization granted by the administrator in A2A. For more information, access [How to manage authorizations in A2A](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a).
- A valid OAuth 2.0 access token. For more information, access [How to authenticate an application in A2A](/v4-2/docs/how-to-authenticate-an-application-in-a2a).
- The access policies referenced in `access_group_id` must already exist. To create one, access [POST | Create access policy](/v4-2/docs/api-v2-post-create-access-policy).
- Each access policy must be an active PAM access policy, released to the application's authorization in A2A. For more information, access [How to manage authorizations in A2A](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a).

---

## Request

`POST` `/api/v2/iam/user-groups/{id}/access-policies`

### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | Yes | Unique identification code of the user group. |

### Headers

| Header | Required | Description |
| --- | --- | --- |
| `Content-Type` | Yes | Must be `application/json`. |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `bindings` | array[object] | Yes | Bindings to create or update. The array must hold at least one value. |
| `bindings[].access_group_id` | integer | Yes | Unique identification code of the access policy to bind. |
| `bindings[].profile` | string | Yes | Role the binding grants to the members of the group. Allowed values: `user`, `approver`, `user_approver`. |
| `bindings[].level` | integer | Yes | Approval level of the binding. Allowed values: `1`, `2`, `3`. |

Attention

`access_group_id` and `level` must be sent as JSON integers. Responses return identification codes as strings, such as `"5"` in `access_group.id`, so convert the value before you send it back. A string value returns `422` with the code `api.validation.required_field`.

---

### Example request

`POST` `{{url}}/api/v2/iam/user-groups/7/access-policies`

#### Body

```
{
  "bindings": [
    {
      "access_group_id": 1,
      "profile": "user",
      "level": 1
    },
    {
      "access_group_id": 2,
      "profile": "approver",
      "level": 2
    }
  ]
}
```

---

## Response

```
HTTP/1.1 201 Created
Location: /api/v2/iam/user-groups/7/access-policies
X-Request-Id: 7f3c1a90-2c4e-4b1a-9f5e-0a2b7c9d1e34
```

### Example response body

```
{
  "data": {
    "binding_ids": ["200", "201"]
  },
  "meta": {
    "links": {
      "self": "/api/v2/iam/user-groups/7/access-policies"
    }
  }
}
```

---

## Response body fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | object | The created or updated bindings. |
| `data.binding_ids` | array[string] | Identification codes of the bindings. Keep these values, they are what identifies a binding when you remove it. |
| `meta` | object | Resource metadata. |
| `meta.links.self` | string | Path of the access policies sub-resource. |

---

## Errors

| HTTP code | Message | Possible cause | Solution |
| --- | --- | --- | --- |
| `401` | `api.auth.unauthorized` | The access token is missing, invalid, or has expired. | Request a new access token. |
| `404` | `api.resource.not_found` | The user group does not exist or is outside the scope of the authorization. An access policy outside the scope never returns `404`; it returns `422`. | Check the user group's identification code and the authorization scope. |
| `422` | `api.validation.required_field` | The body does not carry `bindings`, a binding is missing one of its fields, or `access_group_id` was sent as a string. | Add the missing field, or send `access_group_id` as an integer, and resend the request. |
| `422` | `api.validation.invalid_type` | An entry in `bindings` is not an object. | Send each binding as an object and resend the request. |
| `422` | `api.validation.invalid_reference` | An `access_group_id` does not exist, is not a PAM access policy, or is not released to the application's authorization in A2A. The message is `One or more access policies not found.`, with one entry in `details` for each rejected `access_group_id`. Nothing is saved. | Check the codes and the access policies released to the authorization, and resend the request. |
| `422` | `api.validation.access_policy.not_bindable` | An access policy released to the application's authorization is inactive. Only active PAM access policies released to the authorization can be bound. The message is `One or more access policies cannot be bound to a user group: inactive, or of a type the user group screen does not offer.` | Activate the access policy and resend the request. |
| `422` | `api.enum.invalid_value` | The `profile` is outside its allowed list, or the `level` is not the integer `1`, `2`, or `3`. | Check the allowed values and resend the request. |
| `429` | `api.rate_limit_exceeded` | The request rate limit was exceeded. | Wait the number of seconds returned in the `Retry-After` header and try again. |

For authentication error messages and the `403` versus `404` policy, access [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors).