--- title: "End-to-End Example: Users & Groups (IAM APIs)" slug: "end-to-end-example-users-groups-iam-apis" updated: 2025-12-19T15:42:28Z published: 2025-12-19T15:42:28Z canonical: "docs.ssw.splashtop.com/end-to-end-example-users-groups-iam-apis" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.ssw.splashtop.com/llms.txt > Use this file to discover all available pages before exploring further. # End-to-End Example: Users & Groups (IAM APIs) This guide demonstrates how to automate **Users & Groups** operations using **SSW IAM APIs**. ### Supported operations - List users (organization members) - List groups - List group members - Add a user to a group - Remove a user from a group - (Optional) Approve / reject a group-join request (if approval flow is enabled) - Update a group - Delete a group > ❌ **Not supported via public API** > > > - Creating users > - Creating groups --- ## 1) Prerequisites ### 1.1 Base URL Use your tenant environment base URL, for example: ``` https://{your_tenant_URL} ``` ### 1.2 Authentication All IAM APIs require an **IAM access token**. ``` Authorization: Bearer Accept: application/json ``` --- ## 2) Common Request Headers For most requests: ``` Accept: application/json Authorization: Bearer ``` For JSON body requests (PUT / POST): ``` Content-Type: application/json ``` > Browser-specific headers such as `sec-fetch-*` or `referer` are **not required** for API clients. --- ## 3) Step-by-Step Workflow --- ### Step A — List users (organization members) #### API ``` GET /iam/v1/organization/members ``` #### When to use - Retrieve a paginated list of users (members) in the organization - Identify a target `user_id` for group membership operations #### Common query parameters (documented) - `page` - `page_size` - `search` - `filter` #### Example request (minimal) ``` curl 'https://{your_tenant_URL}/iam/v1/organization/members?page=1&page_size=30' \ -H 'accept: application/json' \ -H 'authorization: Bearer ' ``` #### Example request (observed in Web UI) ``` curl 'https://{your_tenant_URL}/iam/v1/organization/members?page=1&page_size=30&order=status+asc&roles=&groups=&active=' \ -H 'accept: application/json, text/plain, */*' \ -H 'authorization: Bearer ' ``` > **Note** Parameters such as `order`, `roles`, `groups`, and `active` are observed from the Web UI and may vary by deployment or version. #### Example response (illustrative) ``` { "code": 0, "data": { "members": [ { "user_id": "user_123", "email": "user@example.com", "status": "active" } ], "page": 1, "page_size": 30, "total": 100 } } ``` --- ### Step B — List groups (by organization) #### API ``` GET /iam/v1/organization/{organization_id}/groups ``` #### When to use - Retrieve the `group_id` you want to manage - Validate that a group exists before managing membership #### Example request ``` ORG_ID="" curl "https://{your_tenant_URL}/iam/v1/organization/${ORG_ID}/groups?page=1&page_size=50" \ -H 'accept: application/json' \ -H 'authorization: Bearer ' ``` #### Example response (illustrative) ``` { "code": 0, "data": [ { "group_id": "grp_001", "name": "IT Admins" } ] } ``` --- ### Step C — List group members #### API ``` GET /iam/v1/group/members ``` #### When to use - Confirm whether a user is already a member of a group - Inspect membership before add/remove operations #### Required query parameter - `group_id` #### Example request ``` GROUP_ID="" curl "https://{your_tenant_URL}/iam/v1/group/members?group_id=${GROUP_ID}&page=1&page_size=50" \ -H 'accept: application/json' \ -H 'authorization: Bearer ' ``` #### Example response (illustrative) ``` { "code": 0, "data": { "members": [ { "user_id": "user_123", "email": "user@example.com" } ] } } ``` --- ### Step D — Add a user to a group #### API ``` POST /iam/v1/group/{group_id}/members/{user_id} ``` #### When to use - Assign an existing user to an existing group #### Example request ``` GROUP_ID="" USER_ID="" curl -X POST "https://{your_tenant_URL}/iam/v1/group/${GROUP_ID}/members/${USER_ID}" \ -H 'accept: application/json' \ -H 'authorization: Bearer ' ``` #### Example response (illustrative) ``` { "code": 0, "message": "success" } ``` --- ### Step E — (Optional) Approve / reject a group membership request Some deployments require approval before a user becomes an active group member. --- #### Approve membership request **API** ``` POST /iam/v1/group/{group_id}/members/{user_id}/approval ``` ``` curl -X POST "https://{your_tenant_URL}/iam/v1/group/${GROUP_ID}/members/${USER_ID}/approval" \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'authorization: Bearer ' \ -d '{}' ``` --- #### Reject membership request **API** ``` POST /iam/v1/group/{group_id}/members/{user_id}/reject ``` ``` curl -X POST "https://{your_tenant_URL}/iam/v1/group/${GROUP_ID}/members/${USER_ID}/reject" \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'authorization: Bearer ' \ -d '{}' ``` > **Note** The exact request body fields depend on the `UserJoinGroupRequest` definition. Refer to the **API Reference** for details. --- ### Step F — Remove a user from a group #### API ``` DELETE /iam/v1/group/{group_id}/members/{user_id} ``` #### When to use - Remove a user’s membership from a group - This does **not** delete the user or the group #### Example request ``` curl -X DELETE "https://{your_tenant_URL}/iam/v1/group/${GROUP_ID}/members/${USER_ID}" \ -H 'accept: application/json' \ -H 'authorization: Bearer ' ``` #### Example response (illustrative) ``` { "code": 0, "message": "success" } ``` --- ### Step G — Update a group (metadata) #### API ``` PUT /iam/v1/group ``` #### When to use - Rename a group - Update group properties allowed by `GroupRequest` #### Example request (template) ``` curl -X PUT "https://{your_tenant_URL}/iam/v1/group" \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'authorization: Bearer ' \ -d '{ "group_id": "", "name": "New Group Name" }' ``` > Use the **API Reference** for the full `GroupRequest` schema. --- ### Step H — Delete a group #### API ``` DELETE /iam/v1/group/{group_id} ``` #### When to use - Remove a group (typically after ensuring it is not in use) #### Example request ``` curl -X DELETE "https://{your_tenant_URL}/iam/v1/group/${GROUP_ID}" \ -H 'accept: application/json' \ -H 'authorization: Bearer ' ``` --- ## 4) Notes & Limitations (Customer-facing) - User creation is **not supported** via public IAM APIs - Group creation is **not supported** via public IAM APIs - Membership management **is supported**: - List group members - Add user to group - Remove user from group - Optional approval / reject flows - Some filtering and sorting parameters on member list APIs may be **UI-specific** and can vary by environment ---