Security Principals

Security principals are typically unique identifiers for Windows Advanced Directory groups but can also be unique identifiers for individuals. This Public Stable API allows you to get (one or many), create (one or bulk), update, and delete security principals.

An array of security principals HREFs can be passed into rules and rulesets in the consuming_security_principals array.

Note

The common schema consuming_security_principals has been replaced by two other APIs: consuming_security_principals_get and consuming_security_principals_put

Security Principals API Methods

Security Principals Methods	HTTP	URI
Get Security Principals	`GET`	`[api_version][org_href]/security_principals/`
Get a Security Principal	`GET`	`[api_version][org_href]/security_principals/sid`
Create a Security Principal	`POST`	`[api_version][org_href]/security_principals/`
Bulk create Security Principals	`PUT`	`[api_version][org_href]/security_principals/bulk_create`
Update a Security Principal	`PUT`	`[api_version][org_href]/security_principals/sid`
Delete a Security Principal	`DELETE`	`[api_version][org_href]/security_principals/sid`

Query Parameters

The only required parameter for all API methods is org_id.

Parameter	Description	Type	Required
`org_id`	Organization ID	Integer	Yes
`max_results`	Maximum number of entries to return	Integer	No
`name`	Name of security principal to filter by	String	GET, PUT: No POST: Yes
`sid`	SID of security principal to filter by	String	GET: No POST, PUT, DELETE: Yes

Response Properties

Parameter	Description	Type
`href`	URI of security principal	String
`sid`	Active Directory SID	String
`name`	Name of security principal	String
`used_by_ruleset`	Flag to indicate if this security principal is being used by a ruleset	Boolean
`deleted`	Flag to indicate if the security principal has been deleted.	Boolean

Get Security Principals

This GET command, by default, returns information for 100 security principals if max_results is not specified.

A maximum value of up to 500 can be specified for max_results. To return more than 500 security principals, see Asynchronous GET Collections.

Curl Command to Get Security Principals

curl -X GET https://pce.my-company.com:8443/api/v2/security_principals -u $KEY:$TOKEN -H 'Accept: application/json'

Example JSON Response Body

{
 "sid": "string",
 "name": "string",
 "description": "string"
}

Get a specified Security Principal

This GET command returns information about one specific security principal indicated by its sid.

Curl Command to Get a Security Principal

curl -X GET https://pce.my-company.com:8443/api/v2/security_principals/{sid} -u $KEY:$TOKEN -H 'Accept: application/json'

Example JSON Response Body

{
  "sid": "string",
  "name": "string",
  "description": "string"
}

Create a Security Principal

This POST command, on success, returns the HREF of the created security principal.

Curl Command to Create a Security Principal

curl -X POST https://pce.my-company.com:8443/api/v2/security_principals -u $KEY:$TOKEN -H 'Content-Type: application/json'

Example JSON Request Body

{
  "sid": "string",
  "name": "string",
  "description": "string"
}

Bulk Create Security Principals

This PUT command creates multiple security principals.

A maximum of 2,000 security principals can be added to this API in a call. On success, this API returns an array containing the HREFs of the created security principals.

Curl Command to Bulk Create Security Principals

curl -X PUT https://pce.my-company.com:8443/api/v2/security_principals/bulk_create -u $KEY:$TOKEN -H 'Content-Type: application/json'

Example JSON Request Body

[
  {
    "sid": "string",
    "name": "string",
    "description": "string"
  },
  {
    "sid": "string_2",
    "name": "string_2",
    "description": "string_2"
  }
]

Update a Security Principal

This PUT command updates a security principal.

Curl Command to Update a Security Principal

curl -X PUT https://pce.my-company.com:8443/api/v2/security_principals/{sid} -u $KEY:$TOKEN -H 'Content-Type: application/json'

Example JSON Request Body

{
  "name": "string",
  "description": "string"
}

Delete a Security Principal

This command deletes a security principal.

Curl Command to Delete a Security Principal

curl -X DELETE https://pce.my-company.com:8443/api/v2/security_principals/{sid} -u $KEY:$TOKEN

This command returns 204 No Content for success.

REST APIs for 23.5