Skip to content
Hyperproof API
/
/
Role Assignments API

Role Assignments API (1.0)

Provides access to the roles that are assigned to users in the context of a Hyperproof object.

Download OpenAPI description
roleassignments.openapi.json
roleassignments.openapi.yaml
Languages
Servers
Mock server
https://developer.hyperproof.app/_mock/hyperproof-api/roleassignments/roleassignments.openapi
Hyperproof US
https://api.hyperproof.app/v1/roleassignments
Hyperproof EU
https://api.hyperproof.eu/v1/roleassignments
Hyperproof Gov
https://api.hyperproofgov.app/v1/roleassignments

Add Role Assignment

Request

POST /

Description

Adds a new role assignment for a user on an object.

Security
oauth2
Bodyapplication/jsonrequired
roleKindstring(FacePileRoleKind)required

The user's role kind on an object. Manager has full administrative permissions. Contributor has full edit permissions. Viewer has read-only access to the object and its details. Auditor has read-only access specifically for compliance review purposes.

Enum"manager""contributor""auditor""viewer"
principalIdstring(uuid)required

The unique identifier of the user or group to assign the role to. Must be an active user identifier or group identifier that matches the principalType.

Example: "456e7890-e89b-12d3-a456-426614174000"
principalTypestring(ObjectType)required

The type of the object.

Enum"audit""connection""control""controlScope""domain""freshnessHistory""exportFile""label""organization""organizationUser"
targetObjectIdstring(uuid)required

The unique identifier of the target object to assign the role on

Example: "321e0987-e89b-12d3-a456-426614174000"
targetObjectTypestring(ObjectType)required

The type of the object.

Enum"audit""connection""control""controlScope""domain""freshnessHistory""exportFile""label""organization""organizationUser"
messagestring or null

Optional message to include with the role assignment notification

Example: "Adding you as control manager"
curl -i -X POST \
  https://developer.hyperproof.app/_mock/hyperproof-api/roleassignments/roleassignments.openapi/ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "roleKind": "manager",
    "principalId": "456e7890-e89b-12d3-a456-426614174000",
    "principalType": "user",
    "targetObjectId": "321e0987-e89b-12d3-a456-426614174000",
    "targetObjectType": "control",
    "message": "Adding you as control manager"
  }'

Responses

Role assignment created successfully

Bodyapplication/json
idstring(uuid)required

The unique identifier for the role assignment

Example: "123e4567-e89b-12d3-a456-426614174000"
roleIdstring(uuid)required

The unique identifier of the role being assigned

Example: "987e6543-e21b-12d3-a456-426614174000"
roleKindstring(FacePileRoleKind)required

The user's role kind on an object. Manager has full administrative permissions. Contributor has full edit permissions. Viewer has read-only access to the object and its details. Auditor has read-only access specifically for compliance review purposes.

Enum"manager""contributor""auditor""viewer"
principalIdstring(uuid)required

The unique identifier of the user being assigned the role

Example: "456e7890-e89b-12d3-a456-426614174000"
principalTypestring(ObjectType)required

The type of the object.

Enum"audit""connection""control""controlScope""domain""freshnessHistory""exportFile""label""organization""organizationUser"
principalOrgIdstring(uuid)

The unique identifier of the organization of the principal user

Example: "789e0123-e89b-12d3-a456-426614174000"
targetObjectIdstring(uuid)required

The unique identifier of the object the role is assigned on

Example: "321e0987-e89b-12d3-a456-426614174000"
targetObjectTypestring(ObjectType)required

The type of the object.

Enum"audit""connection""control""controlScope""domain""freshnessHistory""exportFile""label""organization""organizationUser"
targetOrgIdstring(uuid)

The unique identifier of the organization of the target object

Example: "789e0123-e89b-12d3-a456-426614174000"
sourceObjectIdstring or null(uuid)

The unique identifier of the source object if the role assignment on the target object is inherited

Example: "555e6666-e89b-12d3-a456-426614174000"
sourceObjectTypestring or null

The type of the object.

Enum"audit""connection""control""controlScope""domain""freshnessHistory""exportFile""label""organization""organizationUser"
Example: "Program"
groupIdstring or null(uuid)

The unique identifier of the group if this is a group role assignment

groupNamestring or null

The name of the group if this is a group role assignment

groupRoleAssignmentIdstring or null(uuid)

The unique identifier of the group role assignment if inherited from group

createdBystring(uuid)

The unique identifier of the user who created the role assignment

Example: "111e2222-e89b-12d3-a456-426614174000"
createdOnstring(date-time)

The date the role assignment was created (ISO-8601 format)

Example: "2024-01-15T10:30:00Z"
updatedBystring(uuid)

The unique identifier of the user who last updated the role assignment

Example: "111e2222-e89b-12d3-a456-426614174000"
updatedOnstring(date-time)

The date the role assignment was updated (ISO-8601 format)

Example: "2024-01-15T10:30:00Z"
Response
application/json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "roleId": "987e6543-e21b-12d3-a456-426614174000",
  "roleKind": "contributor",
  "principalId": "456e7890-e89b-12d3-a456-426614174000",
  "principalType": "user",
  "principalOrgId": "789e0123-e89b-12d3-a456-426614174000",
  "targetObjectId": "321e0987-e89b-12d3-a456-426614174000",
  "targetObjectType": "control",
  "targetOrgId": "789e0123-e89b-12d3-a456-426614174000",
  "sourceObjectId": "555e6666-e89b-12d3-a456-426614174000",
  "sourceObjectType": "Program",
  "groupId": null,
  "groupName": null,
  "groupRoleAssignmentId": null,
  "createdBy": "111e2222-e89b-12d3-a456-426614174000",
  "createdOn": "2024-01-15T10:30:00Z",
  "updatedBy": "111e2222-e89b-12d3-a456-426614174000",
  "updatedOn": "2024-01-15T10:30:00Z"
}

Get Role Assignments Filtered

Request

POST /

Description

Gets the set of role assignments matching the supplied filter.

Security
oauth2
Bodyapplication/jsonrequired
objectIdsArray of strings(uuid)

The list of target object identifiers to filter role assignments by

objectTypestring(ObjectType)

The type of the object.

Enum"audit""connection""control""controlScope""domain""freshnessHistory""exportFile""label""organization""organizationUser"
userIdsArray of strings(uuid)

The list of principal user identifiers to filter role assignments by

Example: ["456e7890-e89b-12d3-a456-426614174000"]
roleAssignmentIdsArray of strings(uuid)

The list of unique identifiers for role assignments to return

directAssignmentsOnlyboolean

Flag indicating whether to exclude returning inherited role assignments

Default false
Example: true
groupIdsArray of strings(uuid)

The list of group identifiers to filter role assignments by

curl -i -X POST \
  https://developer.hyperproof.app/_mock/hyperproof-api/roleassignments/roleassignments.openapi/filter \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "objectType": "control",
    "userIds": [
      "456e7890-e89b-12d3-a456-426614174000"
    ],
    "directAssignmentsOnly": true
  }'

Responses

Successful response

Bodyapplication/jsonArray [
idstring(uuid)required

The unique identifier for the role assignment

Example: "123e4567-e89b-12d3-a456-426614174000"
roleIdstring(uuid)required

The unique identifier of the role being assigned

Example: "987e6543-e21b-12d3-a456-426614174000"
roleKindstring(FacePileRoleKind)required

The user's role kind on an object. Manager has full administrative permissions. Contributor has full edit permissions. Viewer has read-only access to the object and its details. Auditor has read-only access specifically for compliance review purposes.

Enum"manager""contributor""auditor""viewer"
principalIdstring(uuid)required

The unique identifier of the user being assigned the role

Example: "456e7890-e89b-12d3-a456-426614174000"
principalTypestring(ObjectType)required

The type of the object.

Enum"audit""connection""control""controlScope""domain""freshnessHistory""exportFile""label""organization""organizationUser"
principalOrgIdstring(uuid)

The unique identifier of the organization of the principal user

Example: "789e0123-e89b-12d3-a456-426614174000"
targetObjectIdstring(uuid)required

The unique identifier of the object the role is assigned on

Example: "321e0987-e89b-12d3-a456-426614174000"
targetObjectTypestring(ObjectType)required

The type of the object.

Enum"audit""connection""control""controlScope""domain""freshnessHistory""exportFile""label""organization""organizationUser"
targetOrgIdstring(uuid)

The unique identifier of the organization of the target object

Example: "789e0123-e89b-12d3-a456-426614174000"
sourceObjectIdstring or null(uuid)

The unique identifier of the source object if the role assignment on the target object is inherited

Example: "555e6666-e89b-12d3-a456-426614174000"
sourceObjectTypestring or null

The type of the object.

Enum"audit""connection""control""controlScope""domain""freshnessHistory""exportFile""label""organization""organizationUser"
Example: "Program"
groupIdstring or null(uuid)

The unique identifier of the group if this is a group role assignment

groupNamestring or null

The name of the group if this is a group role assignment

groupRoleAssignmentIdstring or null(uuid)

The unique identifier of the group role assignment if inherited from group

createdBystring(uuid)

The unique identifier of the user who created the role assignment

Example: "111e2222-e89b-12d3-a456-426614174000"
createdOnstring(date-time)

The date the role assignment was created (ISO-8601 format)

Example: "2024-01-15T10:30:00Z"
updatedBystring(uuid)

The unique identifier of the user who last updated the role assignment

Example: "111e2222-e89b-12d3-a456-426614174000"
updatedOnstring(date-time)

The date the role assignment was updated (ISO-8601 format)

Example: "2024-01-15T10:30:00Z"
]
Response
application/json
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "roleId": "987e6543-e21b-12d3-a456-426614174000",
    "roleKind": "contributor",
    "principalId": "456e7890-e89b-12d3-a456-426614174000",
    "principalType": "user",
    "principalOrgId": "789e0123-e89b-12d3-a456-426614174000",
    "targetObjectId": "321e0987-e89b-12d3-a456-426614174000",
    "targetObjectType": "control",
    "targetOrgId": "789e0123-e89b-12d3-a456-426614174000",
    "sourceObjectId": "555e6666-e89b-12d3-a456-426614174000",
    "sourceObjectType": "Program",
    "groupId": null,
    "groupName": null,
    "groupRoleAssignmentId": null,
    "createdBy": "111e2222-e89b-12d3-a456-426614174000",
    "createdOn": "2024-01-15T10:30:00Z",
    "updatedBy": "111e2222-e89b-12d3-a456-426614174000",
    "updatedOn": "2024-01-15T10:30:00Z"
  }
]

Update Role Assignment

Request

PATCH /

Description

Updates an existing role assignment.

Security
oauth2
Path
idstring(uuid)required

Role assignment ID

Bodyapplication/jsonrequired
roleKindstring(FacePileRoleKind)required

The user's role kind on an object. Manager has full administrative permissions. Contributor has full edit permissions. Viewer has read-only access to the object and its details. Auditor has read-only access specifically for compliance review purposes.

Enum"manager""contributor""auditor""viewer"
curl -i -X PATCH \
  'https://developer.hyperproof.app/_mock/hyperproof-api/roleassignments/roleassignments.openapi/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "roleKind": "contributor"
  }'

Responses

Role assignment updated successfully

Bodyapplication/json
idstring(uuid)required

The unique identifier for the role assignment

Example: "123e4567-e89b-12d3-a456-426614174000"
roleIdstring(uuid)required

The unique identifier of the role being assigned

Example: "987e6543-e21b-12d3-a456-426614174000"
roleKindstring(FacePileRoleKind)required

The user's role kind on an object. Manager has full administrative permissions. Contributor has full edit permissions. Viewer has read-only access to the object and its details. Auditor has read-only access specifically for compliance review purposes.

Enum"manager""contributor""auditor""viewer"
principalIdstring(uuid)required

The unique identifier of the user being assigned the role

Example: "456e7890-e89b-12d3-a456-426614174000"
principalTypestring(ObjectType)required

The type of the object.

Enum"audit""connection""control""controlScope""domain""freshnessHistory""exportFile""label""organization""organizationUser"
principalOrgIdstring(uuid)

The unique identifier of the organization of the principal user

Example: "789e0123-e89b-12d3-a456-426614174000"
targetObjectIdstring(uuid)required

The unique identifier of the object the role is assigned on

Example: "321e0987-e89b-12d3-a456-426614174000"
targetObjectTypestring(ObjectType)required

The type of the object.

Enum"audit""connection""control""controlScope""domain""freshnessHistory""exportFile""label""organization""organizationUser"
targetOrgIdstring(uuid)

The unique identifier of the organization of the target object

Example: "789e0123-e89b-12d3-a456-426614174000"
sourceObjectIdstring or null(uuid)

The unique identifier of the source object if the role assignment on the target object is inherited

Example: "555e6666-e89b-12d3-a456-426614174000"
sourceObjectTypestring or null

The type of the object.

Enum"audit""connection""control""controlScope""domain""freshnessHistory""exportFile""label""organization""organizationUser"
Example: "Program"
groupIdstring or null(uuid)

The unique identifier of the group if this is a group role assignment

groupNamestring or null

The name of the group if this is a group role assignment

groupRoleAssignmentIdstring or null(uuid)

The unique identifier of the group role assignment if inherited from group

createdBystring(uuid)

The unique identifier of the user who created the role assignment

Example: "111e2222-e89b-12d3-a456-426614174000"
createdOnstring(date-time)

The date the role assignment was created (ISO-8601 format)

Example: "2024-01-15T10:30:00Z"
updatedBystring(uuid)

The unique identifier of the user who last updated the role assignment

Example: "111e2222-e89b-12d3-a456-426614174000"
updatedOnstring(date-time)

The date the role assignment was updated (ISO-8601 format)

Example: "2024-01-15T10:30:00Z"
Response
application/json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "roleId": "987e6543-e21b-12d3-a456-426614174000",
  "roleKind": "contributor",
  "principalId": "456e7890-e89b-12d3-a456-426614174000",
  "principalType": "user",
  "principalOrgId": "789e0123-e89b-12d3-a456-426614174000",
  "targetObjectId": "321e0987-e89b-12d3-a456-426614174000",
  "targetObjectType": "control",
  "targetOrgId": "789e0123-e89b-12d3-a456-426614174000",
  "sourceObjectId": "555e6666-e89b-12d3-a456-426614174000",
  "sourceObjectType": "Program",
  "groupId": null,
  "groupName": null,
  "groupRoleAssignmentId": null,
  "createdBy": "111e2222-e89b-12d3-a456-426614174000",
  "createdOn": "2024-01-15T10:30:00Z",
  "updatedBy": "111e2222-e89b-12d3-a456-426614174000",
  "updatedOn": "2024-01-15T10:30:00Z"
}

Delete Role Assignment

Request

DELETE /

Description

Deletes a role assignment.

Security
oauth2
Path
idstring(uuid)required

Role assignment ID

curl -i -X DELETE \
  'https://developer.hyperproof.app/_mock/hyperproof-api/roleassignments/roleassignments.openapi/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Role assignment deleted successfully

® 2026 Hyperproof All Rights Reserved.