Skip to main content
POST
/
api
/
v1
/
orgs
/
{org}
/
principals
/
byids
Retrieve principals by reference
curl --request POST \
  --url https://auth.cognite.com/api/v1/orgs/{org}/principals/byids \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "id": "5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT"
    }
  ],
  "ignoreUnknownIds": false
}
'
{
  "items": [
    {
      "id": "5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT",
      "type": "SERVICE_ACCOUNT",
      "name": "My service account",
      "createdBy": {
        "orgId": "my-org",
        "userId": "-user-string-id-aBc123"
      },
      "createdTime": 1730204346000,
      "lastUpdatedTime": 1730204346000,
      "pictureUrl": "<string>",
      "externalId": "my.known.id",
      "description": "This is a service account used by data pipeline A-xxx"
    }
  ]
}

Path Parameters

org
string
required

ID of an organization The ID of an organization

Required string length: 3 - 64
Pattern: ^([a-z][a-z0-9-]{1,62}[a-z0-9])$
Example:

"my-org"

Body

application/json

A request to retrieve principals by reference.

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

items
object[]
required
Required array length: 1 - 100 elements

Either a principal ID, or a principal external ID

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.

Response

200 - application/json

A list of principals.

items
object[]
required

A principal

Last modified on April 23, 2026