Sync Group API

The sync-group endpoint allows you to create, update, or delete groups (collections). This endpoint automatically handles group creation, updates, and deletion based on the provided parameters.

Endpoint

POST /sync-group

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

Header	Required	Description
domain	Yes	The domain/group_name identifier for your tenant
Authorization	Yes	Bearer token from generate-client-auth-token
Content-Type	Yes	Must be application/json

Request Body

{
  group_id?: string;           // Optional: Group identifier (required for updates/deletes)
  group_name?: string;         // Required for create: Name of the group
  group_description?: string;  // Optional: Description of the group
  is_delete?: boolean;         // Optional: Set to true to delete the group
  // ... other optional fields
}

Request Parameters

group_id (optional)

• Type: string
• Description: Unique identifier for the group. Required when updating or deleting a group
• Example: "group-123" or "550e8400-e29b-41d4-a716-446655440000"

group_name (required for create)

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

group_description (optional)

• Type: string
• Description: Description of the group
• Example: "This is a description of my group"

is_delete (optional)

• Type: boolean
• Description: Set to true to delete the group. When deleting, group_id must be provided
• Default: false

Success Response

Creating a Group

Status Code: 200

{
  statusCode: 200;
  data: {
    group_id: string;           // Unique group identifier
    group_name: string;         // Group name
    group_description?: string; // Group description (if provided)
    created_at: string;         // ISO timestamp
    updated_at: string;         // ISO timestamp
    // ... other group fields
  };
  message: "OKAY";
}

Updating a Group

Status Code: 200

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

Deleting a Group

Status Code: 200

{
  statusCode: 200;
  data: {
  }
  message: "OKAY";
}

Error Responses

Missing Required Fields (435)

{
  statusCode: 435;
  data: {
  }
  message: "Missing required fields: group_name";
}

Unauthorized (403)

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

Causes:

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

Not Found (437)

{
  statusCode: 437;
  data: {
  }
  message: "ENTRY_NOT_FOUND";
}

Causes:

• Attempting to update or delete a group that doesn't exist
• Invalid group_id provided

Server Fault (500)

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

Example Requests

Example 1: Create a New Group

This example shows the complete flow from authentication to group creation:

# 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: Create group using the auth token
curl -X POST https://api.example.com/sync-group \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "domain: my-domain" \
  -d '{
    "group_name": "My New Group",
    "group_description": "This is a description of my group"
  }'

Response:

{
  "statusCode": 200,
  "data": {
    "group_id": "group-abc-123-def-456",
    "group_name": "My New Group",
    "group_description": "This is a description of my group",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "message": "OKAY"
}

Example 2: Update a Group

curl -X POST https://api.example.com/sync-group \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {auth_token}" \
  -H "domain: my-domain" \
  -d '{
    "group_id": "group-abc-123-def-456",
    "group_name": "Updated Group Name",
    "group_description": "Updated description"
  }'

Example 3: Delete a Group

curl -X POST https://api.example.com/sync-group \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {auth_token}" \
  -H "domain: my-domain" \
  -d '{
    "is_delete": true,
    "group_id": "group-abc-123-def-456"
  }'

Try It Out

API Configuration

Base URL

Authentication

Auth Token *Token obtained from the generate-client-auth-token endpoint

Domain *The domain/group_name identifier for your tenant

Group Details

Group IDOptional. Required for updates and deletes. If not provided for create, a new group ID will be generated

Delete GroupWhen checked, group_id is required and the group will be deleted

Group Information

Group Name *Name of the group (required for create)

Group DescriptionOptional description of the group

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: Create group
async function createGroup(
  authToken: string,
  groupName: string,
  groupDescription?: string
) {
  const response = await fetch("https://api.example.com/sync-group", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${authToken}`,
      domain: "my-domain",
    },
    body: JSON.stringify({
      group_name: groupName,
      group_description: groupDescription,
    }),
  });

  const result = await response.json();

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

  return result.data;
}

// Step 3: Update group
async function updateGroup(
  authToken: string,
  groupId: string,
  updates: { group_name?: string; group_description?: string }
) {
  const response = await fetch("https://api.example.com/sync-group", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${authToken}`,
      domain: "my-domain",
    },
    body: JSON.stringify({
      group_id: groupId,
      ...updates,
    }),
  });

  const result = await response.json();

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

  return result.data;
}

// Step 4: Delete group
async function deleteGroup(authToken: string, groupId: string) {
  const response = await fetch("https://api.example.com/sync-group", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${authToken}`,
      domain: "my-domain",
    },
    body: JSON.stringify({
      is_delete: true,
      group_id: groupId,
    }),
  });

  const result = await response.json();

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

  return result.data;
}

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

    // Create group
    const group = await createGroup(
      authToken,
      "My New Group",
      "This is a description"
    );
    console.log("Group created:", group.group_id);

    // Update group
    const updatedGroup = await updateGroup(authToken, group.group_id, {
      group_name: "Updated Group Name",
    });
    console.log("Group updated:", updatedGroup.group_id);

    // Delete group
    await deleteGroup(authToken, group.group_id);
    console.log("Group deleted");
  } catch (error) {
    console.error("Error:", error);
  }
}

Behavior Notes

Group Creation

• If group_id is not provided, a new group is created
• group_name is required for group creation
• A unique group_id is automatically generated if not provided

Group Updates

• When group_id is provided and is_delete is false or not set, the group is updated
• Only provided fields are updated; omitted fields remain unchanged
• Updates happen synchronously

Group Deletion

• When is_delete is true, group_id must be provided
• Deletion is permanent and cannot be undone
• All associated data with the group may be deleted

Related Documentation

• Groups Overview - Learn about groups concepts
• Fetch Groups API - Retrieve list of groups
• Client Credentials API - Authentication endpoint
• API Guidelines - General API response formats and error codes