Skip to main content

1E 23.11 (SaaS)

Principals

Entity - Role Based Access Control - Interrogates the Principal table in the database

Verb

Request

Notes

Permissions required

GET - all

/Consumer/Principals

Gets list of all Principals (users) and their details

  • Read

Returns Unauthorized (401) if user does not have the required permissions.

GET - single

/Consumer/Principals /{principalId}

Returns all the details for the specified Principal ID

  • Read

Returns Unauthorized (401) if user does not have the required permissions.

GET - for specific role

/Consumer/Principals /Role/{roleId}

Returns all principals for a specific role

  • Read

Returns Unauthorized (401) if user does not have the required permissions.

GET

/Consumer/Principals/ PermissionsAdmins

Returns all principals who have write permission to security

None

POST

/Consumer/Principals

Creates a Principal record.

External Id is the Active Directory SID for the account or group.

Example Request

{
  "ExternalId": "8E527555-2D1C-4CD5-AC55-1B44F314DC65",
  "PrincipalName": "dev101\TchynAdmin",
  "Email": "TchynAdmin@dev101.local"  
}

Example Response

{
  "Id": 17,
  "ExternalId": "8E527555-2D1C-4CD5-AC55-1B44F314DC65",
  "PrincipalName": "dev101\TchynAdmin",
  "Email": "TchynAdmin@dev101.local",
  "CreatedTimestampUtc": "2015-09-16T14:04:05.8636311Z",
  "ModifiedTimestampUtc": "2015-09-16T14:04:05.8636311Z"
}
  • Write

Returns Unauthorized (401) if user does not have the required permissions.

PUT

/Consumer/Principals

Modifies a Principal record.

External Id is the Active Directory SID for the account or group.

Example Request

{
  "Id": 17,
  "ExternalId": "8E527555-2D1C-4CD5-AC55-1B44F314DC65",
  "PrincipalName": "dev101\TchynAdmin",
  "Email": "TchynAdmin@dev101.local"  
}

Example Response

{
  "Id": 17,
  "ExternalId": "8E527555-2D1C-4CD5-AC55-1B44F314DC65",
  "PrincipalName": "dev101\TchynAdmin",
  "Email": "TchynAdmin@dev101.local",
  "CreatedTimestampUtc": "2015-09-16T14:04:05.86",
  "ModifiedTimestampUtc": "2015-09-16T14:04:06.8776311Z"
}
  • Write

Returns Unauthorized (401) if user does not have the required permissions.

DELETE

/Consumer/Principals /{principalId}

Delete the Principal ID if it exists.

Otherwise "ExceptionMessage": "Principal record with Id={id} was not found" is returned.

New in version 8.0: An error will be returned if deleting a Principal that has any assignments to Management Groups / Roles.

  • Delete

Returns Unauthorized (401) if user does not have the required permissions.

DELETE

/Consumer/Principals

Minimum API version 4.0

Deletes multiple principals.

System principals cannot be deleted.

Body of the request should contain a collection of principals Ids in an array.

New in version 8.0: An error will be returned if deleting a Principal that has any assignments to Management Groups / Roles.

Requires 'Delete' permission on 'Security' securable type

PUT

/Consumer/Principals/Enable

Minimum API version 4.0

Enables multiple principals.

Body of the request should contain a collection of principals Ids in an array.

Requires 'Write' permission on 'Security' securable type

PUT

/Consumer/Principals/Disable

Minimum API version 4.0

Disables multiple principals.

Body of the request should contain a collection of principals Ids in an array.

Requires 'Write' permission on 'Security' securable type