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
}
'import requests
url = "https://auth.cognite.com/api/v1/orgs/{org}/principals/byids"
payload = {
"items": [{ "id": "5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT" }],
"ignoreUnknownIds": False
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
items: [{id: '5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT'}],
ignoreUnknownIds: false
})
};
fetch('https://auth.cognite.com/api/v1/orgs/{org}/principals/byids', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://auth.cognite.com/api/v1/orgs/{org}/principals/byids",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'items' => [
[
'id' => '5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT'
]
],
'ignoreUnknownIds' => false
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://auth.cognite.com/api/v1/orgs/{org}/principals/byids"
payload := strings.NewReader("{\n \"items\": [\n {\n \"id\": \"5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT\"\n }\n ],\n \"ignoreUnknownIds\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://auth.cognite.com/api/v1/orgs/{org}/principals/byids")
.header("Content-Type", "application/json")
.body("{\n \"items\": [\n {\n \"id\": \"5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT\"\n }\n ],\n \"ignoreUnknownIds\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://auth.cognite.com/api/v1/orgs/{org}/principals/byids")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"items\": [\n {\n \"id\": \"5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT\"\n }\n ],\n \"ignoreUnknownIds\": false\n}"
response = http.request(request)
puts response.read_body{
"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"
}
]
}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.
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
}
'import requests
url = "https://auth.cognite.com/api/v1/orgs/{org}/principals/byids"
payload = {
"items": [{ "id": "5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT" }],
"ignoreUnknownIds": False
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
items: [{id: '5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT'}],
ignoreUnknownIds: false
})
};
fetch('https://auth.cognite.com/api/v1/orgs/{org}/principals/byids', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://auth.cognite.com/api/v1/orgs/{org}/principals/byids",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'items' => [
[
'id' => '5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT'
]
],
'ignoreUnknownIds' => false
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://auth.cognite.com/api/v1/orgs/{org}/principals/byids"
payload := strings.NewReader("{\n \"items\": [\n {\n \"id\": \"5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT\"\n }\n ],\n \"ignoreUnknownIds\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://auth.cognite.com/api/v1/orgs/{org}/principals/byids")
.header("Content-Type", "application/json")
.body("{\n \"items\": [\n {\n \"id\": \"5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT\"\n }\n ],\n \"ignoreUnknownIds\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://auth.cognite.com/api/v1/orgs/{org}/principals/byids")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"items\": [\n {\n \"id\": \"5yAFQRAATb7vtWGp4gvbJD3wE7VS81CGuQ7EZT\"\n }\n ],\n \"ignoreUnknownIds\": false\n}"
response = http.request(request)
puts response.read_body{
"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
ID of an organization The ID of an organization
Required string length:
3 - 64Pattern:
^([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.
Required array length:
1 - 100 elementsEither a principal ID, or a principal external ID
- Option 1
- Option 2
Show child attributes
Show child attributes
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.
A principal
- Option 1
- Option 2
Show child attributes
Show child attributes
Last modified on August 21, 2026
⌘I