> ## Documentation Index > Fetch the complete documentation index at: https://docs.opal.dev/llms.txt > Use this file to discover all available pages before exploring further. # Add role assignments > Grants one or more principals (user, group, or resource) access to one or more entities (resource or group). The request body is batched to match the GraphQL `addRoleAssignments` mutation, which this endpoint thin-wraps. The caller must hold the `EDIT_ASSIGNMENTS` role permission on every entity in the batch. Omit `access_level_remote_id` for entities that have a single default access level. Omit `duration_minutes` (or send `0`) for an indefinite grant. **Atomicity:** the batch is applied as a single transaction. If any entry fails input validation, authorization, lookup, or creation, **no entries are created** and the response identifies the first failing entry's `entity_id` and `principal_id` (and the request-array index for input validation errors). Clients should retry with the offending entry removed; partial-success is intentionally not supported, matching the semantics of the GraphQL `addRoleAssignments` mutation that this endpoint wraps. Prefer this endpoint for batch or programmatic use (e.g. Terraform). For a single grant on a specific entity/principal pair, the per-pair endpoints — `/resources/{id}/users/{id}`, `/groups/{id}/users/{id}`, `/groups/{id}/resources/{id}`, `/groups/{id}/containing-groups`, `/resources/{id}/non-human-identities/{id}` — are often simpler. ## OpenAPI ````yaml https://app.opal.dev/openapi.yaml post /role-assignments openapi: 3.1.0 info: contact: email: hello@opal.dev name: Opal Team url: https://www.opal.dev/ description: >- The Opal API is a RESTful API that allows you to interact with the Opal Security platform programmatically. title: Opal API version: '1.0' servers: - description: Production url: https://api.opal.dev/v1 security: [] tags: - name: access-rules description: Operations related to access rules - name: apps description: Operations related to apps - name: bundles description: Operations related to bundles - name: campaigns description: Operations related to access review campaigns - name: configuration-templates description: Operations related to configuration templates - name: delegations description: Operations related to request reviewer delegations - name: event-streams description: Operations related to event streaming connections - name: events description: Operations related to events - name: groups description: Operations related to groups - name: group-bindings description: Operations related to group bindings - name: idp-group-mappings description: Operations related to IDP group mappings - name: message-channels description: Operations related to message channels - name: non-human-identities description: Operations related to non-human identities - name: on-call-schedules description: Operations related to on-call schedules - name: opal-queries description: Operations related to OpalQuery - name: opal-scripts description: Operations related to OpalScripts - name: owners description: Operations related to owners - name: requests description: Operations related to requests - name: resources description: Operations related to resources - name: role-assignments description: >- Operations related to role assignments (general grants between an entity and a principal) - name: paladin description: Operations related to Paladin - name: sessions description: Operations related to sessions - name: tags description: Operations related to tags - name: tokens description: Operations related to API tokens - name: uars description: Operations related to UARs. Deprecated in favor of the `campaigns` API. - name: users description: Operations related to users paths: /role-assignments: post: tags: - role-assignments summary: Add role assignments description: > Grants one or more principals (user, group, or resource) access to one or more entities (resource or group). The request body is batched to match the GraphQL `addRoleAssignments` mutation, which this endpoint thin-wraps. The caller must hold the `EDIT_ASSIGNMENTS` role permission on every entity in the batch. Omit `access_level_remote_id` for entities that have a single default access level. Omit `duration_minutes` (or send `0`) for an indefinite grant. **Atomicity:** the batch is applied as a single transaction. If any entry fails input validation, authorization, lookup, or creation, **no entries are created** and the response identifies the first failing entry's `entity_id` and `principal_id` (and the request-array index for input validation errors). Clients should retry with the offending entry removed; partial-success is intentionally not supported, matching the semantics of the GraphQL `addRoleAssignments` mutation that this endpoint wraps. Prefer this endpoint for batch or programmatic use (e.g. Terraform). For a single grant on a specific entity/principal pair, the per-pair endpoints — `/resources/{id}/users/{id}`, `/groups/{id}/users/{id}`, `/groups/{id}/resources/{id}`, `/groups/{id}/containing-groups`, `/resources/{id}/non-human-identities/{id}` — are often simpler. operationId: addRoleAssignments requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddRoleAssignmentsRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/AddRoleAssignmentsResponse' description: The requested role assignments were created. '400': description: > Invalid request body: unknown field, missing required field, malformed JSON, invalid enum (entity_type must be RESOURCE or GROUP; principal_type must be RESOURCE, GROUP, or USER), negative duration_minutes, or role_assignments batch size outside the allowed range. '403': description: >- Caller is not authorized to edit role assignments on one or more of the entities. '404': description: >- One or more referenced entities or principals does not exist in the organization. '409': description: | One of the requested role assignments already exists. The error message identifies the offending entity_id and principal_id so a batch client can locate the colliding entry. Matches the convention of the per-pair endpoints (`/resources/{id}/users/{id}`, `/groups/{id}/users/{id}`), which also return 409 for the same condition. '422': description: | Request was syntactically valid but could not be fulfilled. Includes group nesting cycles, self-grants, invalid durations, access-level mismatches, assignments on computed groups or non-requestable resources, and unsupported entity/principal type combinations. security: - BearerAuth: [] components: schemas: AddRoleAssignmentsRequest: description: Request body for `POST /role-assignments`. type: object required: - role_assignments properties: role_assignments: description: The list of role assignments to add. items: $ref: '#/components/schemas/AddRoleAssignmentInput' minItems: 1 maxItems: 100 type: array AddRoleAssignmentsResponse: description: Response body for `POST /role-assignments`. type: object required: - task_ids - entries properties: task_ids: description: >- Opaque IDs of push tasks enqueued to propagate the new assignments to end systems. Each ID is a base64-encoded, URL-safe string that mirrors the identifier returned by the GraphQL `addRoleAssignments` mutation. items: type: string type: array entries: description: One entry per role assignment created, in request order. items: $ref: '#/components/schemas/AddRoleAssignmentsEntry' type: array AddRoleAssignmentInput: description: A single role assignment to create in a batch add request. type: object required: - entity_id - entity_type - principal_id - principal_type properties: entity_id: description: The ID of the entity (resource or group) being accessed. example: 1b978423-db0a-4037-a4cf-f79c60cb67b3 format: uuid type: string entity_type: description: >- The type of the entity being accessed. Must be `RESOURCE` or `GROUP`. allOf: - $ref: '#/components/schemas/EntityTypeEnum' principal_id: description: >- The ID of the principal (user, group, or resource) being granted access. example: 29827fb8-f2dd-4e80-9576-28e31e9934ac format: uuid type: string principal_type: description: >- The type of the principal being granted access. Must be `RESOURCE`, `GROUP`, or `USER`. allOf: - $ref: '#/components/schemas/EntityTypeEnum' access_level_remote_id: description: >- Remote ID of the access level to grant. Omit for entities that only have a single default access level. nullable: true type: string duration_minutes: description: >- Duration of the grant in minutes. Omit or send `0` for an indefinite grant. minimum: 0 nullable: true type: integer AddRoleAssignmentsEntry: description: A single entry in the result of `POST /role-assignments`. type: object required: - role_assignment properties: role_assignment: $ref: '#/components/schemas/RoleAssignment' EntityTypeEnum: description: The type of an entity. enum: - GROUP - RESOURCE - USER example: GROUP type: string RoleAssignment: description: >- A role assignment representing access granted to a principal for an entity. type: object required: - id - entity_id - entity_type - principal_id - principal_type properties: id: description: Unique identifier for the role assignment. format: uuid type: string entity_id: description: The ID of the entity (resource or group) being accessed. format: uuid type: string entity_type: $ref: '#/components/schemas/EntityTypeEnum' principal_id: description: The ID of the principal being granted access. format: uuid type: string principal_type: $ref: '#/components/schemas/EntityTypeEnum' access_level: description: >- The level of access granted. Null when the entity does not define access levels. allOf: - $ref: '#/components/schemas/ResourceAccessLevel' nullable: true expiration: description: When this access expires. Null when the grant is indefinite. format: date-time nullable: true type: string granted_at: description: When this access was first granted. format: date-time nullable: true type: string ResourceAccessLevel: description: >- # Access Level Object ### Description The `AccessLevel` object is used to represent the level of access that a principal has. The "default" access level is a `AccessLevel` object whose fields are all empty strings. ### Usage Example View the `AccessLevel` of a resource/user or resource/group pair to see the level of access granted to the resource. example: access_level_name: AdminRole access_level_remote_id: arn:aws:iam::590304332660:role/AdministratorAccess properties: access_level_name: description: The human-readable name of the access level. example: AdminRole type: string access_level_remote_id: description: The machine-readable identifier of the access level. example: arn:aws:iam::590304332660:role/AdministratorAccess type: string required: - access_level_name - access_level_remote_id type: object securitySchemes: BearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.