Skip to main content
PUT
/
v1
/
organizations
/
{organization_id}
/
users
/
{user_id}
/
roles
cURL
curl --request PUT \
  --url https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}/roles \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-organization-secret: <x-organization-secret>' \
  --data '
{
  "access_roles": [
    "admin",
    "provider"
  ]
}
'
{
  "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"
}

​
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

{
  "access_roles": ["admin", "provider"]
}

​
Assign Single Role

{
  "access_roles": ["receptionist"]
}

​
Request Fields

FieldTypeRequiredDescription
access_rolesstring[]YesArray of roles to assign to the user

​
Valid Roles

The following roles can be assigned via this API:
RoleDescription
adminAdministrator with extensive permissions
providerHealthcare provider/prescriber
receptionistManage Patients (no script access)
rx_readerRead-only access to prescriptions (needs to be combined with receptionist)
rx_queue_managerManage prescription queues coming soon

​
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)

{
  "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

{
    "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

{
    "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)

{
    "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

FieldTypeDescription
user_idstringParchment’s unique user identifier
access_rolesstring[]Updated array of roles assigned to user

​
Common Response Fields

All responses include these standard fields:
FieldTypeDescription
successbooleanIndicates if the request was successful
statusCodenumberHTTP status code
timestampstringISO 8601 timestamp of the response
requestIdstringUnique identifier for debugging

​
Status Codes

CodeStatusDescription
200OKUser roles successfully updated
400Bad RequestInvalid request format or invalid parameters
401UnauthorizedAuthentication required or token invalid
403ForbiddenInsufficient permissions (missing update:user scope)
404Not FoundUser not found
409ConflictRole update conflict
422Unprocessable EntityRequest validation failed
429Too Many RequestsRate limit exceeded
500Internal Server ErrorUnexpected server error

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-organization-secret
string
required

Organization secret for authentication - provided by Parchment

Path Parameters

​
organization_id
string<uuid>
required

Organization ID

​
user_id
string<uuid>
required

User ID

Body

application/json

User roles data to update in Parchment

User roles update request

​
access_roles
enum<string>[]
required

Array of roles to assign to the user

Valid user roles. Note: owner, support, and member roles cannot be assigned via API.

Available options:
admin,
provider,
receptionist,
rx_reader,
rx_queue_manager
Example:
["admin", "provider"]

Response

User roles updated successfully

​
success
boolean
required

Indicates if the request was successful

Example:

true

​
statusCode
integer
required

HTTP status code

Example:

200

​
message
string
required

Human-readable success message

Example:

"User roles updated successfully"

​
data
object
required

User roles update response data

​
timestamp
string<date-time>
required

ISO 8601 timestamp of the response

Example:

"2024-01-15T10:30:00.000Z"

​
requestId
string
required

Unique identifier for request tracing

Example:

"req_1705312200000_abc123"

​
pagination
object

Pagination information for list operations