Avnology ID
SDKsTypeScript SDKAdmin API

Group Management

Create and manage static and dynamic groups with the TypeScript SDK.

Group Management

Groups organize users into collections for permission assignment. Static groups have manually managed membership. Dynamic groups use CEL rules to automatically include users based on their profile attributes.

createGroup()

client.admin.createGroup(params: CreateGroupParams): Promise<Group>

Parameters

NameTypeRequiredDescription
namestringyesGroup display name
descriptionstringnoGroup description
organizationIdstringyesOrganization this group belongs to
type"static" | "dynamic"yesGroup type
rulestringconditionalCEL expression (required for dynamic groups)

Basic usage

// Static group -- manual membership
const engineers = await client.admin.createGroup({
  name: "Engineering",
  description: "Engineering team members",
  organizationId: "org_abc123",
  type: "static",
});

// Dynamic group -- automatic membership based on traits
const euUsers = await client.admin.createGroup({
  name: "EU Users",
  description: "Users with EU timezone",
  organizationId: "org_abc123",
  type: "dynamic",
  rule: 'traits.timezone.startsWith("Europe/")',
});

Dynamic group rule examples

// Users with a specific email domain
'traits.email.endsWith("@acme.com")'

// Users with admin role
'traits.role == "admin"'

// Users created in the last 30 days
'identity.created_at > now() - duration("720h")'

// Users with verified email and phone
'traits.email_verified == true && traits.phone_verified == true'

// Users in a specific locale
'traits.locale in ["en-US", "en-GB", "en-AU"]'

addGroupMember()

Add a user to a static group.

await client.admin.addGroupMember({
  groupId: "grp_abc123",
  userId: "usr_jane",
});

removeGroupMember()

Remove a user from a static group.

await client.admin.removeGroupMember({
  groupId: "grp_abc123",
  userId: "usr_jane",
});

listGroupMembers()

List members of a group (works for both static and dynamic).

const result = await client.admin.listGroupMembers({
  groupId: "grp_abc123",
  pageSize: 50,
});

for (const member of result.members) {
  console.log(member.userId, member.email, member.joinedAt);
}

listGroups()

List groups in an organization.

const result = await client.admin.listGroups({
  organizationId: "org_abc123",
  pageSize: 25,
});

for (const group of result.groups) {
  console.log(group.id, group.name, group.type, group.memberCount);
}

Common errors

Error classHTTP statusWhen
NotFoundError404Group not found
ValidationError422Invalid CEL rule syntax
ForbiddenError403Insufficient permissions
ConflictError409User already a member (static groups)

See also

On this page