> ## Documentation Index > Fetch the complete documentation index at: https://docs.nx1cloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Grant workspace roles to a Keycloak role > Replace the workspace roles held by everyone with a Keycloak role. The submitted list is the complete set. Granting checks that the role exists in the realm: an unknown role returns 422, and 503 means Keycloak couldn't be reached to check it. Nothing is granted in either case. Send an empty list to revoke. Revoking doesn't contact Keycloak, so you can remove grants for a role that has since been deleted. Requires a Keycloak session; PSK credentials can't change who has access. **Required roles**: `workspace_admin` or `nx1_decisions_admin` ## OpenAPI ````yaml put /api/decisions/{workspace}/role-grants/{keycloak_role} openapi: 3.1.0 info: title: Nx1 AI API description: | AI API for Nx1 Data Platform Management and Automated Data Tasks. Authentication is required via PSK in Authorization header. Default PSK is | [ask a friend] | version: 0.10.2 servers: [] security: [] paths: /api/decisions/{workspace}/role-grants/{keycloak_role}: put: tags: - Decisions summary: Grant workspace roles to a Keycloak role description: |- Replace the workspace roles held by everyone with a Keycloak role. The submitted list is the complete set. Granting checks that the role exists in the realm: an unknown role returns 422, and 503 means Keycloak couldn't be reached to check it. Nothing is granted in either case. Send an empty list to revoke. Revoking doesn't contact Keycloak, so you can remove grants for a role that has since been deleted. Requires a Keycloak session; PSK credentials can't change who has access. **Required roles**: `workspace_admin` or `nx1_decisions_admin` operationId: set_role_grant_api_decisions__workspace__role_grants__keycloak_role__put parameters: - name: workspace in: path required: true schema: type: string maxLength: 64 pattern: ^[a-z0-9][a-z0-9-]{0,63}$ description: Workspace slug. title: Workspace description: Workspace slug. - name: keycloak_role in: path required: true schema: type: string minLength: 1 maxLength: 255 description: Keycloak realm role name. URL-encode it. title: Keycloak Role description: Keycloak realm role name. URL-encode it. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MemberGrantRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/MemberListResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Content '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - OAuth2AuthorizationCodeBearer: [] - APIKeyHeader: [] components: schemas: MemberGrantRequest: properties: roles: items: $ref: '#/components/schemas/DecisionWorkspaceRoleEnum' type: array title: Roles description: >- Complete set of workspace roles for this grantee. Replaces any existing grants — send an empty list to revoke. type: object required: - roles title: MemberGrantRequest MemberListResponse: properties: workspace: type: string title: Workspace role_grants: items: $ref: '#/components/schemas/RoleGrantResponse' type: array title: Role Grants description: >- Workspace roles granted to Keycloak roles. This is how access is granted. members: items: $ref: '#/components/schemas/MemberResponse' type: array title: Members description: >- Legacy grants made directly to users. Still honoured and revocable, but no new ones can be made — replace them with role grants. type: object required: - workspace title: MemberListResponse ErrorResponse: properties: error: type: string title: Error description: A brief description of the error that occurred. code: type: integer title: Code description: The HTTP status code associated with the error. default: 500 type: object required: - error title: ErrorResponse DecisionWorkspaceRoleEnum: type: string enum: - workspace_admin - author - approver - simulator - viewer title: DecisionWorkspaceRoleEnum description: |- Per-workspace role grants. ``workspace_admin`` deliberately cannot approve: separation of duties is the point of the matrix, and approval requires a distinct ``approver`` identity. RoleGrantResponse: properties: keycloak_role: type: string title: Keycloak Role description: Keycloak realm role name. roles: items: $ref: '#/components/schemas/DecisionWorkspaceRoleEnum' type: array title: Roles granted_by: type: string title: Granted By description: Who made the most recent grant. granted_at: type: string format: date-time title: Granted At description: When the most recent grant was made. type: object required: - keycloak_role - roles - granted_by - granted_at title: RoleGrantResponse description: Workspace roles held by everyone with one Keycloak role. MemberResponse: properties: subject: type: string title: Subject description: Keycloak username. roles: items: $ref: '#/components/schemas/DecisionWorkspaceRoleEnum' type: array title: Roles granted_by: type: string title: Granted By granted_at: type: string format: date-time title: Granted At type: object required: - subject - roles - granted_by - granted_at title: MemberResponse description: A legacy grant made directly to one user. securitySchemes: OAuth2AuthorizationCodeBearer: type: oauth2 flows: authorizationCode: scopes: {} authorizationUrl: >- https://sso-rapid.rapid.nx1cloud.com/realms/rapid/protocol/openid-connect/auth tokenUrl: >- https://sso-rapid.rapid.nx1cloud.com/realms/rapid/protocol/openid-connect/token APIKeyHeader: type: apiKey in: header name: Authorization-PSK ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.