Skip to main content

REST APIs 25.3

Security Principals

Security principals are typically unique identifiers for Windows Advanced Directory groups, but they 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

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.

Update a Security Principal

Use a PUT command to update a security principal.

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.

Security Principals Reference

This topic provides properties, parameters, and examples of security principals.

Query parameters for security principals

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

Properties for security principals

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 a ruleset is using this security principal.

Boolean

deleted

Flag to indicate if the security principal has been deleted.

Boolean

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

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"
  }
]

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.