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 <iam_token>
Accept: application/json

2) Common Request Headers

For most requests:

Accept: application/json
Authorization: Bearer <iam_token>

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 <IAM_TOKEN>'

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 <IAM_TOKEN>'

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="<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 <IAM_TOKEN>'

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="<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 <IAM_TOKEN>'

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="<GROUP_ID>"
USER_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 <IAM_TOKEN>'

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 <IAM_TOKEN>' \
  -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 <IAM_TOKEN>' \
  -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 <IAM_TOKEN>'

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 <IAM_TOKEN>' \
  -d '{
    "group_id": "<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 <IAM_TOKEN>'

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