Retrieve principals by reference

Retrieve principals in an organization by ID or external ID.

Service accounts can be retrieved by ID or external ID. Users can be retrieved by ID.

Access control

Requires the caller to be logged into the target organization, or to be an admin in any of its the ancestor organizations.

Securityorg-oidc-token
Request
path Parameters
org
required
string (OrgId) [ 3 .. 64 ] characters ^([a-z][a-z0-9-]{1,62}[a-z0-9])$

ID of an organization

Example: my-org
Request Body schema: application/json
required

A request to retrieve principals by reference.

For now, only service accounts can have an external ID.

required
Array of ReferenceById (object) or ReferenceByExternalId (object) (ReferenceByIdOrExternalId) [ 1 .. 100 ] items
ignoreUnknownIds
boolean
Default: false

If true, IDs that do not match existing principals will be ignored.

If false, the request will fail if any of the IDs do not match existing principals. This is the default behavior.

Responses
200

A list of principals

post/api/v1/orgs/{org}/principals/byids
Request samples
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false
}
Response samples
application/json
{
  • "items": [
    • {
      }
    ]
}
➔ Next to Groups