Skip to main content

Groups Overview

The Groups API allows you to create, manage, and retrieve groups (collections) in the IndexSDK system. Groups serve as containers for organizing documents, plans, and other resources within a tenant domain.

Architecture​

Groups are domain-scoped entities that organize and manage collections of resources. Each group is associated with:

  • A domain (group_name) that identifies the tenant
  • A group_id that uniquely identifies the group
  • A group_name that provides a human-readable name
  • A group_description that describes the group's purpose
  • Various settings and configurations for the group

Authentication Flow​

Before managing groups, you must authenticate using the Client Credentials API to obtain an access token. This token is then used to authenticate requests to group endpoints.

Key Concepts​

Group Creation​

When you create a group using sync-group:

  1. A new group is created with a unique group_id
  2. The group_name is required and must be unique within the domain
  3. Optional group_description can be provided
  4. The group is associated with the authenticated user's domain

Group Management​

Groups can be managed through the sync-group endpoint:

  • Create: Provide group_name (and optionally group_description) without group_id
  • Update: Provide group_id along with fields to update
  • Delete: Set is_delete: true along with group_id

Group Retrieval​

Groups can be retrieved using the fetch-groups endpoint:

  • Returns all groups the authenticated user has access to
  • Access is determined by:
    • User role (admin users see all groups)
    • Direct user-group access mappings
    • Organization-level access

Access Control​

Group access is managed through:

  • Admin users: Have access to all groups in the system
  • Regular users: Have access only to groups explicitly granted to them or groups within their organization

Plans​

Plans are associated with collections (groups) and allow you to organize documents and supplemental benefits. Plans can be:

  • Created, updated, or deleted using the sync-plan endpoint
  • Retrieved individually by plan_id or as a list filtered by collection_id
  • Associated with multiple documents and supplemental benefits

Plan Management​

Plans can be managed through the sync-plan endpoint:

  • Create: Provide plan_name, description, collection_id, and color without plan_id
  • Update: Provide plan_id along with fields to update
  • Delete: Set is_delete: true along with plan_id

Plan Retrieval​

Plans can be retrieved using:

  • get-plans - Returns all plans or plans filtered by collection_id
  • get-plan-details - Returns a specific plan by plan_id with associated documents and benefits

Use Cases​

Groups are used to:

  • Organize documents and resources by category or purpose
  • Manage access control for collections of content
  • Separate different types of content within a tenant
  • Support multi-tenant architectures with domain isolation

Plans are used to:

  • Organize documents within a collection
  • Associate documents with supplemental benefits
  • Create structured document groupings for specific purposes

Next Steps​