52bf0279Identity discovery#
| Property | Value |
|---|---|
| Service | crossfire |
| Operation | principals |
| Method | GET |
| Path | /api/principals |
| Authentication | either |
| Success status | 200 |
| Response data | Paginated collection |
| Request format | json |
| Maximum request body | 2097152 bytes (service default) |
| Permission codes | principal.read |
Listed permission codes are alternatives, not token scopes. The service also checks access to the requested records and rejects stale revisions or controller generations.
Path parameters#
empty object; unknown fields rejected
Validation#
check.emptyReferenced definitions:
Query parameters#
custom validation:
principals
; see function below
Accepted query parameters: kind, search, excludeId.
Query parameters are URL text. The validation function below specifies their format, defaults and combinations. Pagination applies only to operations that use it.
Additional checks#
The following checks apply in addition to the field limits.
Constraint on value:
export function principals(input: unknown) {
const parsed = checked(input, ['kind', 'search', 'excludeId']);
if (!parsed.ok)
return parsed;
const bounds = pagination(parsed.value), kind = check.choice('all', 'human', 'agent')(parsed.value.get('kind') ?? 'all');
if (!bounds.ok)
return bounds;
if (!kind.ok)
return kind;
const search = parsed.value.get('search') ?? '', excludeId = parsed.value.get('excludeId');
if (!check.text(200, 0)(search).ok)
return failure('invalid', 'Invalid search');
if (excludeId !== null) {
const valid = check.identifier(excludeId);
if (!valid.ok)
return valid;
}
return success({ ...bounds.value, kind: kind.value, search, ...(excludeId === null ? {} : { excludeId }) });
}Validation#
query.principalsReferenced definitions:
Request body#
empty object; unknown fields rejected
Validation#
check.emptyReferenced definitions:
Response data#
array; 0–100 entries; item: object; fields below; unknown fields rejected (
principal
)
| Field path | Representation and constraints |
|---|---|
[].principalId | lowercase opaque UUID |
[].matrixUserId | well-formed Matrix user ID; maximum 255 UTF-16 units |
[].kind | human or agent |
[].displayName | string; 1–255 UTF-16 units; well-formed Unicode; no C0/DEL controls |
[].ownerId | lowercase opaque UUID |
[].ownerMatrixId | well-formed Matrix user ID; maximum 255 UTF-16 units |
Validation#
check.list(res.principal, 100)Referenced definitions:
Response envelope#
A successful JSON response contains data and meta. Replace the data placeholder below with the response fields described above. Errors contain error instead of data.
{
"data": "<value matching the response-data validator>",
"meta": {
"requestId": "00000000-0000-0000-0000-000000000001",
"page": 1,
"pageSize": 20,
"totalItems": 0,
"totalPages": 1
}
}