Users and Roles

Users are are people with access to the Drata platform.
Roles grant permissions to Users. The help docs have more information on the default Roles.

List Roles

Find Roles matching the provided filters.

🔒 Requires Roles: List Roles permission.

Securitybearer or oauth2
Request
query Parameters
cursor
string

This parameter is used to paginate through results. No value is needed for the first request. If there are additional results, the response will contain a pagination.cursor value that can be used in the subsequent request to retrieve the next page of results

size
number [ 1 .. 500 ]
Default: 50

Number of results to return

sort
string (SortTypeLimitedEnum)

Which field to sort by

Enum: "createdAt" "updatedAt"
sortDir
string (SortDirectionEnum)

The direction to sort the data

Enum: "ASC" "DESC"
includeTotalCount
boolean

Include total count of all matching records in response. Only honored on first page (when cursor is null).

Example: includeTotalCount=false
expand[]
Array of strings (RoleExpandEnum)

List of subcollections and sub-objects to expand

Items Value: "permissions"
Responses
200

Successful

400

Malformed data and/or validation errors

401

Invalid Authorization

403

You are not allowed to perform this action

412

You must accept the Drata terms and conditions to use the API

500

Internal server error

get/roles
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "role": "ADMIN",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "permissions": [
        • {
          • "id": null,
          • "action": "READ",
          • "subject": "Asset",
          • "createdAt": "2019-08-24T14:15:22Z"
          }
        ]
      }
    ],
  • "pagination": {
    • "cursor": "string",
    • "totalCount": 0
    }
}
Get Role
Get the full detail of a Role record.


🔒 Requires Roles: Get Role permission.


Securitybearer or oauth2 
Request 
path Parameters
required
number or string
An integer Role ID or name prefixed with role:


 
query Parameters
expand[]
Array of strings (RoleExpandEnum) 
List of subcollections and sub-objects to expand


Items Value: "permissions"  
Responses 
200
Successful


400
Malformed data and/or validation errors


401
Invalid Authorization


403
You are not allowed to perform this action


404
Not Found


412
You must accept the Drata terms and conditions to use the API


500
Internal server error


get/roles/{roleId}
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "role": "ADMIN",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "permissions": [
    • {
      • "id": null,
      • "action": "READ",
      • "subject": "Asset",
      • "createdAt": "2019-08-24T14:15:22Z"
      }
    ]
}
List Users with Role
List all Users that have a specific Role assigned.


🔒 Requires Personnel & Users: List Users permission.


Securitybearer or oauth2 
Request 
path Parameters
required
number or string
An integer Role ID or name prefixed with role:


 
query Parameters
cursor
string
This parameter is used to paginate through results. No value is needed for the first request. If there are additional results, the response will contain a pagination.cursor value that can be used in the subsequent request to retrieve the next page of results


 
size
number  [ 1 .. 500 ] 
 Default:  50
Number of results to return


 
sort
string (SortTypeLimitedEnum) 
Which field to sort by


 Enum: "createdAt" "updatedAt"  
sortDir
string (SortDirectionEnum) 
The direction to sort the data


 Enum: "ASC" "DESC"  
includeTotalCount
boolean
Include total count of all matching records in response. Only honored on first page (when cursor is null).


 
 Example:  includeTotalCount=false
expand[]
Array of strings (UserExpandEnum) 
List of subcollections and sub-objects to expand


Items Enum: "backgroundChecks" "documents" "personnel" "identities" "roles"  
firstName
string
Filter users whose first name starts with the provided value (prefix match). For example, firstName=John matches users named John, Johnathan, Johnny, etc.


 
 Example:  firstName=John
lastName
string
Filter users whose last name starts with the provided value (prefix match). For example, lastName=Sm matches users named Smith, Smithson, etc.


 
 Example:  lastName=Doe
Responses 
200
400
Malformed data and/or validation errors


401
Invalid Authorization


403
You are not allowed to perform this action


404
Not Found


412
You must accept the Drata terms and conditions to use the API


500
Internal server error


get/roles/{roleId}/users
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "email": "[email protected]",
      • "firstName": "Sally",
      • "lastName": "Smith",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "jobTitle": "CEO",
      • "avatarUrl": "https://cdn-prod.imgpilot.com/avatar.png",
      • "drataTermsAgreedAt": "2025-07-01T16:45:55.246Z",
      • "roles": [
        • "ROLE",
        • "ANOTHER_ROLE"
        ],
      • "backgroundChecks": [
        • {
          • "id": 0,
          • "userId": 0,
          • "status": "OK",
          • "caseId": "abc123",
          • "caseInvitationId": "abc123",
          • "url": "https://app-stage.karmacheck.com/background_check/aaaaaaaa-bbbb-0000-cccc-dddddddddddd",
          • "manualCheckDate": "2020-07-06",
          • "manuallyCheckUrl": "url.com",
          • "type": "CERTN",
          • "source": "DRATA",
          • "reportData": "string",
          • "outOfScopeReason": "abc123",
          • "outOfScopeAt": "2025-07-01T16:45:55.246Z",
          • "invitationEmail": "[email protected]",
          • "linkedAt": "2025-07-01T16:45:55.246Z",
          • "createdAt": "2025-07-01T16:45:55.246Z",
          • "updatedAt": "2025-07-01T16:45:55.246Z"
          }
        ],
      • "documents": [],
      • "identities": [
        • {
          • "id": 1,
          • "identityId": "1a2b3c",
          • "username": "johndoe",
          • "connectedAt": "2025-07-01T16:45:55.246Z",
          • "disconnectedAt": "2025-07-01T16:45:55.246Z",
          • "hasMfa": true,
          • "userId": 1,
          • "connectionId": 1,
          • "connection": {
            • "id": "1",
            • "clientType": "GOOGLE",
            • "clientId": "drata.com",
            • "clientAlias": "My-connection-alias-1",
            • "state": "ACTIVE",
            • "createdAt": "2025-07-01T16:45:55.246Z",
            • "updatedAt": "2025-07-01T16:45:55.246Z",
            • "connectedAt": "2025-07-01T16:45:55.246Z",
            • "failedAt": "2025-07-01T16:45:55.246Z",
            • "deletedAt": "2025-07-01T16:45:55.246Z"
            },
          • "email": "[email protected]",
          • "secondaryEmail": "[email protected]",
          • "firstName": "John",
          • "lastName": "Doe",
          • "startedAt": "Wed Oct 28 2026",
          • "separatedAt": "Wed Oct 28 2026",
          • "isContractor": true,
          • "jobTitle": "Engineer",
          • "managerId": "x00jk12-2312",
          • "managerName": "Jose Díaz",
          • "createdAt": "2025-07-01T16:45:55.246Z",
          • "updatedAt": "2025-07-01T16:45:55.246Z"
          }
        ]
      }
    ],
  • "pagination": {
    • "cursor": "string",
    • "totalCount": 0
    }
}
List Users
Find Users matching the provided filters.


🔒 Requires Personnel & Users: List Users permission.


Securitybearer or oauth2 
Request 
query Parameters
cursor
string
This parameter is used to paginate through results. No value is needed for the first request. If there are additional results, the response will contain a pagination.cursor value that can be used in the subsequent request to retrieve the next page of results


 
size
number  [ 1 .. 500 ] 
 Default:  50
Number of results to return


 
sort
string (SortTypeLimitedEnum) 
Which field to sort by


 Enum: "createdAt" "updatedAt"  
sortDir
string (SortDirectionEnum) 
The direction to sort the data


 Enum: "ASC" "DESC"  
includeTotalCount
boolean
Include total count of all matching records in response. Only honored on first page (when cursor is null).


 
 Example:  includeTotalCount=false
expand[]
Array of strings (UserExpandEnum) 
List of subcollections and sub-objects to expand


Items Enum: "backgroundChecks" "documents" "personnel" "identities" "roles"  
firstName
string
Filter users whose first name starts with the provided value (prefix match). For example, firstName=John matches users named John, Johnathan, Johnny, etc.


 
 Example:  firstName=John
lastName
string
Filter users whose last name starts with the provided value (prefix match). For example, lastName=Sm matches users named Smith, Smithson, etc.


 
 Example:  lastName=Doe
Responses 
200
Successful


400
Malformed data and/or validation errors


401
Invalid Authorization


403
You are not allowed to perform this action


412
You must accept the Drata terms and conditions to use the API


500
Internal server error


get/users
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "email": "[email protected]",
      • "firstName": "Sally",
      • "lastName": "Smith",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "jobTitle": "CEO",
      • "avatarUrl": "https://cdn-prod.imgpilot.com/avatar.png",
      • "drataTermsAgreedAt": "2025-07-01T16:45:55.246Z",
      • "roles": [
        • "ROLE",
        • "ANOTHER_ROLE"
        ],
      • "backgroundChecks": [
        • {
          • "id": 0,
          • "userId": 0,
          • "status": "OK",
          • "caseId": "abc123",
          • "caseInvitationId": "abc123",
          • "url": "https://app-stage.karmacheck.com/background_check/aaaaaaaa-bbbb-0000-cccc-dddddddddddd",
          • "manualCheckDate": "2020-07-06",
          • "manuallyCheckUrl": "url.com",
          • "type": "CERTN",
          • "source": "DRATA",
          • "reportData": "string",
          • "outOfScopeReason": "abc123",
          • "outOfScopeAt": "2025-07-01T16:45:55.246Z",
          • "invitationEmail": "[email protected]",
          • "linkedAt": "2025-07-01T16:45:55.246Z",
          • "createdAt": "2025-07-01T16:45:55.246Z",
          • "updatedAt": "2025-07-01T16:45:55.246Z"
          }
        ],
      • "documents": [],
      • "identities": [
        • {
          • "id": 1,
          • "identityId": "1a2b3c",
          • "username": "johndoe",
          • "connectedAt": "2025-07-01T16:45:55.246Z",
          • "disconnectedAt": "2025-07-01T16:45:55.246Z",
          • "hasMfa": true,
          • "userId": 1,
          • "connectionId": 1,
          • "connection": {
            • "id": "1",
            • "clientType": "GOOGLE",
            • "clientId": "drata.com",
            • "clientAlias": "My-connection-alias-1",
            • "state": "ACTIVE",
            • "createdAt": "2025-07-01T16:45:55.246Z",
            • "updatedAt": "2025-07-01T16:45:55.246Z",
            • "connectedAt": "2025-07-01T16:45:55.246Z",
            • "failedAt": "2025-07-01T16:45:55.246Z",
            • "deletedAt": "2025-07-01T16:45:55.246Z"
            },
          • "email": "[email protected]",
          • "secondaryEmail": "[email protected]",
          • "firstName": "John",
          • "lastName": "Doe",
          • "startedAt": "Wed Oct 28 2026",
          • "separatedAt": "Wed Oct 28 2026",
          • "isContractor": true,
          • "jobTitle": "Engineer",
          • "managerId": "x00jk12-2312",
          • "managerName": "Jose Díaz",
          • "createdAt": "2025-07-01T16:45:55.246Z",
          • "updatedAt": "2025-07-01T16:45:55.246Z"
          }
        ]
      }
    ],
  • "pagination": {
    • "cursor": "string",
    • "totalCount": 0
    }
}
Get User
Get the full detail of a User record.


🔒 Requires Personnel & Users: Get User permission.


Securitybearer or oauth2 
Request 
path Parameters
required
number or string
A Drata integer ID or an email address of the form 'email:value'.


 
query Parameters
expand[]
Array of strings (UserExpandEnum) 
List of subcollections and sub-objects to expand


Items Enum: "backgroundChecks" "documents" "personnel" "identities" "roles"  
Responses 
200
Successful


400
Malformed data and/or validation errors


401
Invalid Authorization


403
You are not allowed to perform this action


412
You must accept the Drata terms and conditions to use the API


500
Internal server error


get/users/{userId}
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "email": "[email protected]",
  • "firstName": "Sally",
  • "lastName": "Smith",
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "jobTitle": "CEO",
  • "avatarUrl": "https://cdn-prod.imgpilot.com/avatar.png",
  • "drataTermsAgreedAt": "2025-07-01T16:45:55.246Z",
  • "roles": [
    • "ROLE",
    • "ANOTHER_ROLE"
    ],
  • "backgroundChecks": [
    • {
      • "id": 0,
      • "userId": 0,
      • "status": "OK",
      • "caseId": "abc123",
      • "caseInvitationId": "abc123",
      • "url": "https://app-stage.karmacheck.com/background_check/aaaaaaaa-bbbb-0000-cccc-dddddddddddd",
      • "manualCheckDate": "2020-07-06",
      • "manuallyCheckUrl": "url.com",
      • "type": "CERTN",
      • "source": "DRATA",
      • "reportData": "string",
      • "outOfScopeReason": "abc123",
      • "outOfScopeAt": "2025-07-01T16:45:55.246Z",
      • "invitationEmail": "[email protected]",
      • "linkedAt": "2025-07-01T16:45:55.246Z",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z"
      }
    ],
  • "documents": [],
  • "identities": [
    • {
      • "id": 1,
      • "identityId": "1a2b3c",
      • "username": "johndoe",
      • "connectedAt": "2025-07-01T16:45:55.246Z",
      • "disconnectedAt": "2025-07-01T16:45:55.246Z",
      • "hasMfa": true,
      • "userId": 1,
      • "connectionId": 1,
      • "connection": {
        • "id": "1",
        • "clientType": "GOOGLE",
        • "clientId": "drata.com",
        • "clientAlias": "My-connection-alias-1",
        • "state": "ACTIVE",
        • "createdAt": "2025-07-01T16:45:55.246Z",
        • "updatedAt": "2025-07-01T16:45:55.246Z",
        • "connectedAt": "2025-07-01T16:45:55.246Z",
        • "failedAt": "2025-07-01T16:45:55.246Z",
        • "deletedAt": "2025-07-01T16:45:55.246Z"
        },
      • "email": "[email protected]",
      • "secondaryEmail": "[email protected]",
      • "firstName": "John",
      • "lastName": "Doe",
      • "startedAt": "Wed Oct 28 2026",
      • "separatedAt": "Wed Oct 28 2026",
      • "isContractor": true,
      • "jobTitle": "Engineer",
      • "managerId": "x00jk12-2312",
      • "managerName": "Jose Díaz",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z"
      }
    ]
}