Check, grant, revoke, and list permissions using relationship-based access control with the TypeScript SDK.

Permissions

Avnology ID uses relationship-based access control (ReBAC). Permissions are expressed as relationships between subjects (users, groups, service accounts) and objects (organizations, projects, documents).

check()

Check whether a subject has a specific relationship with an object.

client.permissions.check(params: CheckPermissionParams): Promise<boolean>

Parameters

Name	Type	Required	Description
`subject`	`string`	yes	The entity performing the action (e.g., `"user:usr_abc123"`)
`relation`	`string`	yes	The relationship/permission (e.g., `"editor"`, `"viewer"`, `"admin"`)
`object`	`string`	yes	The resource (e.g., `"project:proj_abc123"`)

Returns

Promise<boolean> -- true if the permission exists, false otherwise.

Basic usage

import { AvnologyId } from "@avnology/sdk-typescript";

const client = new AvnologyId({
  baseUrl: "https://api.id.avnology.com",
  apiKey: "ak_live_...",
});

const canEdit = await client.permissions.check({
  subject: "user:usr_abc123",
  relation: "editor",
  object: "project:proj_xyz789",
});

if (canEdit) {
  showEditButton();
} else {
  showReadOnlyView();
}

Check with inheritance

Permissions inherit through the relationship graph. If a user is an admin of an organization, and the organization owns a project, the user is implicitly an admin of the project.

// Jane is an admin of org:acme
// org:acme owns project:website
// Therefore, Jane is an admin of project:website

const isAdmin = await client.permissions.check({
  subject: "user:usr_jane",
  relation: "admin",
  object: "project:website",
});
// true (inherited through org membership)

grant()

Create a permission relationship.

client.permissions.grant(params: GrantPermissionParams): Promise<void>

Parameters

Name	Type	Required	Description
`subject`	`string`	yes	The subject to grant permission to
`relation`	`string`	yes	The relationship to grant
`object`	`string`	yes	The object to grant access to

Basic usage

// Grant Jane editor access to a project
await client.permissions.grant({
  subject: "user:usr_jane",
  relation: "editor",
  object: "project:proj_abc123",
});

// Grant a group viewer access
await client.permissions.grant({
  subject: "group:grp_engineering",
  relation: "viewer",
  object: "project:proj_abc123",
});

revoke()

Remove a permission relationship.

client.permissions.revoke(params: RevokePermissionParams): Promise<void>

Basic usage

await client.permissions.revoke({
  subject: "user:usr_jane",
  relation: "editor",
  object: "project:proj_abc123",
});

listObjects()

List all objects that a subject has a specific relationship with.

client.permissions.listObjects(params: ListObjectsParams): Promise<ObjectList>

Parameters

Name	Type	Required	Description
`subject`	`string`	yes	The subject to query
`relation`	`string`	yes	The relationship to filter by
`objectType`	`string`	yes	The type of objects to return
`pageSize`	`number`	no	Results per page (default: 25)
`pageToken`	`string`	no	Pagination token

Basic usage

// List all projects Jane can edit
const result = await client.permissions.listObjects({
  subject: "user:usr_jane",
  relation: "editor",
  objectType: "project",
});

for (const obj of result.objects) {
  console.log(obj); // "project:proj_abc123", "project:proj_xyz789"
}

listSubjects()

List all subjects that have a specific relationship with an object.

client.permissions.listSubjects(params: ListSubjectsParams): Promise<SubjectList>

Parameters

Name	Type	Required	Description
`object`	`string`	yes	The object to query
`relation`	`string`	yes	The relationship to filter by
`subjectType`	`string`	no	Filter by subject type (e.g., `"user"`, `"group"`)

Basic usage

// List all editors of a project
const result = await client.permissions.listSubjects({
  object: "project:proj_abc123",
  relation: "editor",
});

for (const subject of result.subjects) {
  console.log(subject); // "user:usr_jane", "group:grp_engineering"
}

expand()

Expand a permission to see the full relationship tree (who has access and why).

client.permissions.expand(params: ExpandPermissionParams): Promise<PermissionTree>

Basic usage

const tree = await client.permissions.expand({
  object: "project:proj_abc123",
  relation: "viewer",
});

// tree.type: "union"
// tree.children: [
//   { type: "leaf", subject: "user:usr_jane" },
//   { type: "computed", relation: "editor", children: [...] },
//   { type: "tuple_to_userset", relation: "organization.member", children: [...] }
// ]

Common errors

Error class	HTTP status	When
`ForbiddenError`	403	Insufficient admin permissions
`ValidationError`	422	Invalid subject/relation/object format
`RateLimitError`	429	Too many permission checks

Permissions

Permissions

check()

Parameters

Returns

Basic usage

Check with inheritance

grant()

Parameters

Basic usage

revoke()

Basic usage

listObjects()

Parameters

Basic usage

listSubjects()

Parameters

Basic usage

expand()

Basic usage

Common errors

See also

On this page