Look up groups & permissions

Creating, updating, and deleting users all start by looking up the UIDs you'll reference. This page is the single reference for those lookups.

See Managing users for an overview of the core concepts (groups, profiles, application groups, and asset permissions).

---

User groups

Group UIDs returned here are passed as userGroupUids when creating or updating a user.

GET /v1/organizations/DEMO/groups?pageNumber=1&pageSize=20

Python

import requests

BASE_URL = "https://api.stonal.io/users"
TOKEN = "<access_token>"

resp = requests.get(
    f"{BASE_URL}/v1/organizations/DEMO/groups",
    headers={"Authorization": f"Bearer {TOKEN}"},
    params={"pageNumber": 1, "pageSize": 20},
)
print(resp.status_code, resp.json())

PHP

<?php
$baseUrl = "https://api.stonal.io/users";
$token = "<access_token>";

$ch = curl_init("$baseUrl/v1/organizations/DEMO/groups?pageNumber=1&pageSize=20");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL . $response;
curl_close($ch);

JavaScript

const baseUrl = "https://api.stonal.io/users";
const token = "<access_token>";

const res = await fetch(
  `${baseUrl}/v1/organizations/DEMO/groups?pageNumber=1&pageSize=20`,
  { headers: { Authorization: `Bearer ${token}` } }
);
console.log(res.status, await res.json());

Java

import java.net.URI;
import java.net.http.*;

String baseUrl = "https://api.stonal.io/users";
String token = "<access_token>";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(baseUrl + "/v1/organizations/DEMO/groups?pageNumber=1&pageSize=20"))
    .header("Authorization", "Bearer " + token)
    .GET()
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode() + " " + response.body());

Go

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	baseURL := "https://api.stonal.io/users"
	token := "<access_token>"

	req, _ := http.NewRequest("GET", baseURL+"/v1/organizations/DEMO/groups?pageNumber=1&pageSize=20", nil)
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(out))
}

C#

using System.Net.Http;
using System.Net.Http.Headers;

var baseUrl = "https://api.stonal.io/users";
var token = "<access_token>";

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var response = await client.GetAsync($"{baseUrl}/v1/organizations/DEMO/groups?pageNumber=1&pageSize=20");
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

See Get groups

---

Permissions

Permission UIDs returned here are passed as permissions[].uid when creating or updating a user.

GET /v1/organizations/DEMO/users/permissions?pageNumber=1&pageSize=20&type=...

Python

import requests

BASE_URL = "https://api.stonal.io/users"
TOKEN = "<access_token>"

resp = requests.get(
    f"{BASE_URL}/v1/organizations/DEMO/users/permissions",
    headers={"Authorization": f"Bearer {TOKEN}"},
    params={"pageNumber": 1, "pageSize": 20, "type": "PROFILE"},
)
print(resp.status_code, resp.json())

PHP

<?php
$baseUrl = "https://api.stonal.io/users";
$token = "<access_token>";

$ch = curl_init("$baseUrl/v1/organizations/DEMO/users/permissions?pageNumber=1&pageSize=20&type=PROFILE");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL . $response;
curl_close($ch);

JavaScript

const baseUrl = "https://api.stonal.io/users";
const token = "<access_token>";

const res = await fetch(
  `${baseUrl}/v1/organizations/DEMO/users/permissions?pageNumber=1&pageSize=20&type=PROFILE`,
  { headers: { Authorization: `Bearer ${token}` } }
);
console.log(res.status, await res.json());

Java

import java.net.URI;
import java.net.http.*;

String baseUrl = "https://api.stonal.io/users";
String token = "<access_token>";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(baseUrl + "/v1/organizations/DEMO/users/permissions?pageNumber=1&pageSize=20&type=PROFILE"))
    .header("Authorization", "Bearer " + token)
    .GET()
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode() + " " + response.body());

Go

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	baseURL := "https://api.stonal.io/users"
	token := "<access_token>"

	req, _ := http.NewRequest("GET", baseURL+"/v1/organizations/DEMO/users/permissions?pageNumber=1&pageSize=20&type=PROFILE", nil)
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(out))
}

C#

using System.Net.Http;
using System.Net.Http.Headers;

var baseUrl = "https://api.stonal.io/users";
var token = "<access_token>";

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var response = await client.GetAsync($"{baseUrl}/v1/organizations/DEMO/users/permissions?pageNumber=1&pageSize=20&type=PROFILE");
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

Use the type (and optional subType) query parameters to filter what you need:

To find…	Query filter
Profiles	type=PROFILE
Application groups	type=SCOPE_GROUP&subType=APPLICATION
Companies	type=ASSET&subType=COMPANY
Portfolios	type=ASSET&subType=PORTFOLIO
Facilities	type=ASSET&subType=FACILITY
Building groups	type=ASSET&subType=BUILDING_GROUP
Buildings	type=ASSET&subType=BUILDING
Report groups	type=REPORT_GROUP

Additional filter notes:

• type accepts a comma-separated list (e.g. type=ASSET,PROFILE)
• q does free-text search on permission names
• parentUids combined with level lets you walk the permission hierarchy
  • For assets, level counts the steps along the containment hierarchy: a building in a building group is at level=1 under the group.
  • A portfolio reaches an asset it groups directly at level=1, unless the parent of that asset is in the portfolio too. The asset then follows its parent: a building in a building group of the portfolio is at level=2 under the portfolio.
• withUsers=true includes user counts in the response

See Get permissions

---

Find an existing user

Each user's uid in the results is the identifier you pass to create, update, or delete calls.

GET /v2/organizations/DEMO/users?pageNumber=1&pageSize=20&q=john.doe@example.com

Python

import requests

BASE_URL = "https://api.stonal.io/users"
TOKEN = "<access_token>"

resp = requests.get(
    f"{BASE_URL}/v2/organizations/DEMO/users",
    headers={"Authorization": f"Bearer {TOKEN}"},
    params={"pageNumber": 1, "pageSize": 20, "q": "john.doe@example.com"},
)
print(resp.status_code, resp.json())

PHP

<?php
$baseUrl = "https://api.stonal.io/users";
$token = "<access_token>";

$ch = curl_init("$baseUrl/v2/organizations/DEMO/users?pageNumber=1&pageSize=20&q=john.doe%40example.com");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL . $response;
curl_close($ch);

JavaScript

const baseUrl = "https://api.stonal.io/users";
const token = "<access_token>";

const params = new URLSearchParams({ pageNumber: 1, pageSize: 20, q: "john.doe@example.com" });
const res = await fetch(
  `${baseUrl}/v2/organizations/DEMO/users?${params}`,
  { headers: { Authorization: `Bearer ${token}` } }
);
console.log(res.status, await res.json());

Java

import java.net.URI;
import java.net.http.*;

String baseUrl = "https://api.stonal.io/users";
String token = "<access_token>";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(baseUrl + "/v2/organizations/DEMO/users?pageNumber=1&pageSize=20&q=john.doe%40example.com"))
    .header("Authorization", "Bearer " + token)
    .GET()
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode() + " " + response.body());

Go

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
)

func main() {
	baseURL := "https://api.stonal.io/users"
	token := "<access_token>"

	params := url.Values{"pageNumber": {"1"}, "pageSize": {"20"}, "q": {"john.doe@example.com"}}
	req, _ := http.NewRequest("GET", baseURL+"/v2/organizations/DEMO/users?"+params.Encode(), nil)
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(out))
}

C#

using System.Net.Http;
using System.Net.Http.Headers;

var baseUrl = "https://api.stonal.io/users";
var token = "<access_token>";

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var response = await client.GetAsync(
    $"{baseUrl}/v2/organizations/DEMO/users?pageNumber=1&pageSize=20&q=john.doe%40example.com"
);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

Additional filter parameters:

• permissions — filter by permission label, e.g. permissions=PROFILE:Administrator,SCOPE_GROUP:All
• userGroups — filter by group name, e.g. userGroups=Administrators,Readers

See Get paginated users