> ## Documentation Index > Fetch the complete documentation index at: https://docs.parchmenthealth.io/llms.txt > Use this file to discover all available pages before exploring further. # Update user roles > Updates the roles of a user in Parchment ## Integration Notes 1. **Role Management**: This endpoint specifically handles user role assignments within an organization. 2. **Complete Replacement**: The `access_roles` array completely replaces the user's current roles. 3. **Role Validation**: Invalid roles (not in the allowed list) will cause the request to fail with a 400 error. 4. **Authorization**: Requires `update:user` scope to modify user roles. 5. **Request ID**: Always log the `requestId` for debugging support requests. ## Request ### Update User Roles ```json theme={null} { "access_roles": ["admin", "provider"] } ``` ### Assign Single Role ```json theme={null} { "access_roles": ["receptionist"] } ``` ### Request Fields | Field | Type | Required | Description | | -------------- | --------- | -------- | ------------------------------------ | | `access_roles` | string\[] | Yes | Array of roles to assign to the user | ### Valid Roles The following roles can be assigned via this API: | Role | Description | | ------------------ | -------------------------------------------------------------------------------------------------------------------------- | | `admin` | Administrator with extensive permissions | | `provider` | Healthcare provider/prescriber | | `receptionist` | Manage Patients (no script access) | | `rx_reader` | Read-only access to prescriptions (needs to be combined with `receptionist`) | | `rx_queue_manager` | Manage the prescription queue on behalf of prescribers — includes patient management and read-only access to prescriptions | **`rx_queue_manager` requires provider identity details.** Like `provider`, this role must be backed by a verified healthcare individual (HPI-I, date of birth, sex, qualifications). These details are captured when the user is created — see [Create User](/api-reference/endpoint/v1/create-user). Assigning `rx_queue_manager` via this endpoint does not collect them, so only assign it to users created with the required identity fields; otherwise create the user with the role directly, or backfill the details via [Update User](/api-reference/endpoint/v1/update-user) `provider_details`. ### Validation Rules 1. **Required Field**: `access_roles` is required and must be an array 2. **Non-Empty Array**: `access_roles` must contain at least one role (cannot be empty) 3. **Valid Roles**: All roles must be from the supported roles list ## Response ### Success Response (200 OK) ```json theme={null} { "success": true, "statusCode": 200, "message": "User roles updated successfully", "data": { "user_id": "usr_abc123def456", "access_roles": ["admin", "provider"] }, "timestamp": "2024-01-15T10:30:00.000Z", "requestId": "req_1705312200000_abc123" } ``` ### Bad Request (400 Bad Request) #### Invalid Roles ```json theme={null} { "success": false, "statusCode": 400, "error": { "type": "https://parchment.health/errors/invalid-request", "title": "Invalid request", "detail": "access_roles must be a non-empty array of valid roles" }, "timestamp": "2025-08-24T08:41:50.042Z", "requestId": "1-68aad04d-10c08dde5682893b35b89265" } ``` #### Empty After Filtering ```json theme={null} { "success": false, "statusCode": 400, "error": { "type": "https://parchment.health/errors/invalid-request", "title": "Invalid request", "detail": "access_roles must contain at least one valid role after filtering" }, "timestamp": "2025-08-24T08:41:50.042Z", "requestId": "1-68aad04d-10c08dde5682893b35b89265" } ``` ### User Not Found (404 Not Found) ```json theme={null} { "success": false, "statusCode": 404, "error": { "type": "https://parchment.health/errors/resource-not-found", "title": "Resource not found", "detail": "User not found" }, "timestamp": "2025-08-24T08:43:28.294Z", "requestId": "1-68aad0b0-2f3757b01494507a7802998c" } ``` ## Response Fields ### Success Response Data | Field | Type | Description | | -------------- | --------- | --------------------------------------- | | `user_id` | string | Parchment's unique user identifier | | `access_roles` | string\[] | Updated array of roles assigned to user | ### Common Response Fields All responses include these standard fields: | Field | Type | Description | | ------------ | ------- | --------------------------------------- | | `success` | boolean | Indicates if the request was successful | | `statusCode` | number | HTTP status code | | `timestamp` | string | ISO 8601 timestamp of the response | | `requestId` | string | Unique identifier for debugging | ## Status Codes | Code | Status | Description | | ----- | --------------------- | ---------------------------------------------------- | | `200` | OK | User roles successfully updated | | `400` | Bad Request | Invalid request format or invalid parameters | | `401` | Unauthorized | Authentication required or token invalid | | `403` | Forbidden | Insufficient permissions (missing update:user scope) | | `404` | Not Found | User not found | | `409` | Conflict | Role update conflict | | `422` | Unprocessable Entity | Request validation failed | | `429` | Too Many Requests | Rate limit exceeded | | `500` | Internal Server Error | Unexpected server error | ## OpenAPI ````yaml PUT /v1/organizations/{organization_id}/users/{user_id}/roles openapi: 3.0.1 info: title: Parchment APIs description: >- Parchments API documentation for partner integrations, enabling secure e-prescription services license: name: MIT version: 1.0.0 servers: - url: https://api.sandbox.parchmenthealth.io/external - url: https://api.parchmenthealth.io/external security: - bearerAuth: [] paths: /v1/organizations/{organization_id}/users/{user_id}/roles: put: description: Updates the roles of a user in Parchment parameters: - name: x-organization-secret in: header required: true description: Organization secret for authentication - provided by Parchment schema: type: string - name: organization_id in: path required: true description: Organization ID schema: type: string format: uuid - name: user_id in: path required: true description: User ID schema: type: string format: uuid requestBody: description: User roles data to update in Parchment content: application/json: schema: $ref: '#/components/schemas/UpdateUserRoles' required: true responses: '200': description: User roles updated successfully content: application/json: schema: $ref: '#/components/schemas/UserRolesResponse' example: success: true statusCode: 200 message: User roles updated successfully data: user_id: usr_abc123def456 access_roles: - admin - provider timestamp: '2024-01-15T10:30:00.000Z' requestId: req_1705312200000_abc123 '400': description: Bad Request - Invalid request format content: application/json: schema: $ref: '#/components/schemas/ExternalApiErrorResponse' '401': description: Unauthorized - Authentication required content: application/json: schema: $ref: '#/components/schemas/ExternalApiErrorResponse' '404': description: Not Found - User not found content: application/json: schema: $ref: '#/components/schemas/ExternalApiErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ExternalApiErrorResponse' components: schemas: UpdateUserRoles: type: object description: User roles update request required: - access_roles properties: access_roles: type: array description: Array of roles to assign to the user items: type: string enum: - admin - provider - receptionist - rx_reader - rx_queue_manager description: >- Valid user roles. Note: owner, support, and member roles cannot be assigned via API. example: - admin - provider UserRolesResponse: allOf: - $ref: '#/components/schemas/ExternalApiResponse' - type: object properties: statusCode: example: 200 message: example: User roles updated successfully data: $ref: '#/components/schemas/UserRolesData' ExternalApiErrorResponse: type: object required: - success - statusCode - error - timestamp - requestId properties: success: type: boolean description: Indicates if the request was successful example: false statusCode: type: integer description: HTTP status code example: 400 code: type: string description: Machine-readable operation code identifying the error example: RESOURCE_NOT_FOUND error: type: object description: RFC 7807 compliant error details required: - type - title - detail properties: type: type: string format: uri description: URI identifying the problem type example: https://parchment.health/errors/validation-error title: type: string description: Human-readable summary of the problem example: Validation failed detail: type: string description: Human-readable explanation of the problem example: There were some problems with your input. instance: type: string format: uri description: URI reference to the specific occurrence example: /patients/123 validation: type: array description: Field-level validation errors (for 422 responses) items: type: object properties: field: type: string description: Field name that failed validation message: type: string description: Validation error message code: type: string description: Error code for programmatic handling timestamp: type: string format: date-time description: ISO 8601 timestamp of the response example: '2024-01-15T10:30:00.000Z' requestId: type: string description: Unique identifier for request tracing example: req_1705312200000_def456 meta: type: object description: Additional response metadata properties: apiVersion: type: string description: API version used example: '1.0' ExternalApiResponse: type: object required: - success - statusCode - message - data - timestamp - requestId properties: success: type: boolean description: Indicates if the request was successful example: true statusCode: type: integer description: HTTP status code example: 200 message: type: string description: Human-readable success message example: Success code: type: string description: Machine-readable operation code example: SUCCESS data: type: object description: Response payload data timestamp: type: string format: date-time description: ISO 8601 timestamp of the response example: '2024-01-15T10:30:00.000Z' requestId: type: string description: Unique identifier for request tracing example: req_1705312200000_abc123 pagination: type: object description: Pagination information for list operations properties: count: type: integer description: Number of items in current response hasNext: type: boolean description: Whether more items are available limit: type: integer description: Maximum items per page offset: type: integer description: Starting position of current page lastKey: type: string nullable: true description: >- Opaque cursor for fetching the next page. Use this value as the lastKey query parameter for the next request. If null, no more pages are available UserRolesData: type: object description: User roles update response data required: - user_id - access_roles properties: user_id: type: string description: Parchment's unique identifier for the user example: usr_abc123def456 access_roles: type: array description: Updated array of roles assigned to user items: type: string example: - admin - provider securitySchemes: bearerAuth: type: http scheme: bearer ````