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.
A valid OAuth 2.0 access token. For more information, access 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.
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.

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.