YeshID Groups API [ALPHA]

Last updated: December 22, 2025

This functionality of the YeshID API is under very early ALPHA. Please check in with your YeshID CSM or SE before proceeding with this API.

Group Management API Documentation

This document covers all the API endpoints for managing groups and group membership in YeshID. All endpoints require admin privileges and appropriate API key scopes (`group` for write operations, group or group.readonly for read operations).

Group CRUD Operations

List Groups

GET /api/v1/groups

Lists all groups for the authenticated user's organization with optional filtering and pagination.

Query Parameters:

filter (optional): Filter expression for groups
limit (optional): Maximum number of groups to return
offset (optional): Number of groups to skip for pagination

Response:

{

  "groups": [

    {

      "id": "uuid",

      "orgId": "uuid",

      "name": "string",

      "description": "string",

      "type": "STATIC|DYNAMIC",

      "owners": [/* User objects */],

      "filter": {/* Trigger object for dynamic groups */},

      "isDeleted": false,

      "createdAt": "timestamp",

      "updatedAt": "timestamp",

      "createdById": "uuid",

      "createdBy": {/* User object */},

      "updatedById": "uuid"

    }

  ],

  "total": 0

}

Get Group

GET /api/v1/group/:id

Retrieves a specific group by ID.

Path Parameters:

id: Group UUID

Response:

{

  "group": {

    "id": "uuid",

    "orgId": "uuid",

    "name": "string",

    "description": "string",

    "type": "STATIC|DYNAMIC",

    "owners": [/* User objects */],

    "filter": {/* Trigger object for dynamic groups */},

    "isDeleted": false,

    "createdAt": "timestamp",

    "updatedAt": "timestamp",

    "createdById": "uuid",

    "createdBy": {/* User object */},

    "updatedById": "uuid"

  }

}

Create Group

POST /api/v1/groups

Creates a new group.

Request Body:

{

  "name": "string",

  "description": "string",

  "filter": {/* Trigger object - for dynamic groups */},

  "type": "STATIC|DYNAMIC",

  "owners": ["uuid", "uuid"]

}

Response:

{

  "group": {

    "id": "uuid",

    "orgId": "uuid",

    "name": "string",

    "description": "string",

    "type": "STATIC|DYNAMIC",

    "owners": [/* User objects */],

    "filter": {/* Trigger object for dynamic groups */},

    "isDeleted": false,

    "createdAt": "timestamp",

    "updatedAt": "timestamp",

    "createdById": "uuid",

    "createdBy": {/* User object */},

    "updatedById": "uuid"

  }

}

Update Group

PUT /api/v1/group/:id

Updates an existing group.

Path Parameters:

id: Group UUID

Request Body:

{

  "name": "string",

  "owners": ["uuid", "uuid"],

  "description": "string",

  "filter": {/* Trigger object - for dynamic groups */}

}

Response:

{

  "group": {

    "id": "uuid",

    "orgId": "uuid",

    "name": "string",

    "description": "string",

    "type": "STATIC|DYNAMIC",

    "owners": [/* User objects */],

    "filter": {/* Trigger object for dynamic groups */},

    "isDeleted": false,

    "createdAt": "timestamp",

    "updatedAt": "timestamp",

    "createdById": "uuid",

    "createdBy": {/* User object */},

    "updatedById": "uuid"

  }

}

Delete Group

DELETE /api/v1/group/:id

Deletes a group.

Path Parameters:

id: Group UUID

Response:

{}

Group Member Management

List Group Members

GET /api/v1/group/:id/members

Lists all members of a specific group.

Path Parameters:

id: Group UUID

Response:

{

  "members": [

    {

      "id": "uuid",

      "groupId": "uuid",

      "userId": "uuid",

      "user": {/* User object */}

    }

  ]

}

Add Group Members

POST /api/v1/group/:id/members

Adds users to a group.

Path Parameters:

id: Group UUID

Request Body:

{

  "additions": ["user-uuid", "user-uuid"]

}

Response:

{}

Remove Group Members

DELETE /api/v1/group/:id/members

Removes users from a group.

Path Parameters:

id: Group UUID

Request Body:

{

  "removals": ["user-uuid", "user-uuid"]

}

Response:

{}

Utility Operations

List User Groups

GET /api/v1/user/:id/groups

Lists all groups that a specific user belongs to.

Path Parameters:

id: User UUID

Response:

{

  "groups": [

    {

      "id": "uuid",

      "orgId": "uuid",

      "name": "string",

      "description": "string",

      "type": "STATIC|DYNAMIC",

      "owners": [/* User objects */],

      "filter": {/* Trigger object for dynamic groups */},

      "isDeleted": false,

      "createdAt": "timestamp",

      "updatedAt": "timestamp",

      "createdById": "uuid",

      "createdBy": {/* User object */},

      "updatedById": "uuid"

    }

  ]

}

Evaluate Group Filter

POST /api/v1/groups/evaluate-filter

Evaluates a dynamic group filter to see which users would be included, useful for testing dynamic group rules before creating the group.

Request Body:

{

  "filter": {/* Trigger object representing the filter logic */}

}

Response:

{

  "users": [

    {

      /* UserInfo objects for users that match the filter */

    }

  ]

}

Notes

All routes require admin privileges within the organization
Group types can be either STATIC (manually managed membership) or DYNAMIC (membership determined by filter rules)
Dynamic groups use a filter field containing trigger logic to automatically determine membership
Static groups require manual addition/removal of members via the member management endpoints
Group owners have administrative rights over the group
All UUIDs in path parameters and request/response bodies are standard UUID format
API key scopes: Use group for write operations, group or group.readonly for read operations