Skip to main content

Fetch Groups API

The fetch-groups endpoint allows you to retrieve a list of all groups (collections) that the authenticated user has access to. The endpoint returns groups based on the user's role and access permissions.

Endpoint​

POST /fetch-groups

Authentication​

This endpoint requires authentication using the auth token obtained from generate-client-auth-token.

Include the token in the Authorization header:

Authorization: Bearer {auth_token}

Request Headers​

HeaderRequiredDescription
domainYesThe domain/group_name identifier for your tenant
AuthorizationYesBearer token from generate-client-auth-token
Content-TypeYesMust be application/json

Request Body​

{
  // No body parameters required
}

This endpoint does not require any body parameters. The user's access is determined from the authentication token and domain header.

Success Response​

Status Code: 200

{
  statusCode: 200;
  data: [
    {
      group_id: string;           // Unique group identifier
      group_name: string;         // Group name
      group_description?: string; // Group description
      created_at: string;         // ISO timestamp
      updated_at: string;         // ISO timestamp
      // ... other group fields
    },
    // ... more groups
  ];
  message: "OKAY";
}

Response Fields​

group_id​

  • Type: string
  • Description: Unique identifier for the group
  • Example: "group-123"

group_name​

  • Type: string
  • Description: Name of the group
  • Example: "My Group"

group_description​

  • Type: string (optional)
  • Description: Description of the group
  • Example: "This is a description"

created_at​

  • Type: string
  • Description: ISO timestamp when the group was created
  • Example: "2024-01-15T10:30:00Z"

updated_at​

  • Type: string
  • Description: ISO timestamp when the group was last updated
  • Example: "2024-01-15T10:30:00Z"

Error Responses​

Unauthorized (403)​

{
  statusCode: 403;
  data: {
  }
  message: "UNAUTHORIZED";
}

Causes:

  • Missing or invalid Authorization header
  • Expired or invalid auth token
  • Missing domain header

Server Fault (500)​

{
  statusCode: 500;
  data: {
  }
  message: "SERVER_FAULT";
}

Example Requests​

Example 1: Fetch All Groups​

This example shows the complete flow from authentication to fetching groups:

# Step 1: Generate auth token
curl -X POST https://api.example.com/generate-client-auth-token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "fingerprint": "device-fingerprint-123",
    "user": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "group_name": "my-domain"
    }
  }'

# Response:
# {
#   "statusCode": 200,
#   "data": {
#     "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
#   },
#   "message": "OKAY"
# }

# Step 2: Fetch groups using the auth token
curl -X POST https://api.example.com/fetch-groups \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "domain: my-domain" \
  -d '{}'

Response:

{
  "statusCode": 200,
  "data": [
    {
      "group_id": "group-abc-123",
      "group_name": "My First Group",
      "group_description": "Description of first group",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "group_id": "group-def-456",
      "group_name": "My Second Group",
      "group_description": "Description of second group",
      "created_at": "2024-01-14T09:20:00Z",
      "updated_at": "2024-01-14T09:20:00Z"
    }
  ],
  "message": "OKAY"
}

Try It Out

API Configuration

Authentication

Token obtained from the generate-client-auth-token endpoint
The domain/group_name identifier for your tenant

Request Preview

{}

Integration Example​

Here's a complete JavaScript/TypeScript example showing the full integration:

// Step 1: Generate auth token
async function generateAuthToken() {
  const response = await fetch(
    "https://api.example.com/generate-client-auth-token",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        client_id: "your-client-id",
        client_secret: "your-client-secret",
        fingerprint: "device-fingerprint-123",
        user: {
          first_name: "John",
          last_name: "Doe",
          email: "john.doe@example.com",
          group_name: "my-domain",
        },
      }),
    }
  );

  const result = await response.json();
  return result.data.auth_token;
}

// Step 2: Fetch groups
async function fetchGroups(authToken: string) {
  const response = await fetch("https://api.example.com/fetch-groups", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${authToken}`,
      domain: "my-domain",
    },
    body: JSON.stringify({}),
  });

  const result = await response.json();

  if (result.statusCode !== 200) {
    throw new Error(`Failed to fetch groups: ${result.message}`);
  }

  return result.data;
}

// Usage
async function main() {
  try {
    // Authenticate
    const authToken = await generateAuthToken();
    console.log("Auth token obtained:", authToken);

    // Fetch groups
    const groups = await fetchGroups(authToken);
    console.log(`Found ${groups.length} groups:`);
    groups.forEach((group) => {
      console.log(`- ${group.group_name} (${group.group_id})`);
    });
  } catch (error) {
    console.error("Error:", error);
  }
}

Behavior Notes​

Access Control​

  • Admin users: Receive all groups in the system
  • Regular users: Receive only groups they have access to, either through:
    • Direct user-collection access mappings
    • Organization-level access (all groups in their organization)

Response Ordering​

  • Groups are returned in an unspecified order
  • You may need to sort them client-side if a specific order is required

Empty Results​

  • If the user has no access to any groups, an empty array [] is returned
  • This is not an error condition