Version: v5.0

User Group

Add User Groups

Endpoints

POST /passportsvc/api/v1/usergroups

Request

Body example

Array of UserGroup objects

[
  {
    "_description": "File Contributor",
    "_name": "File Contributor",
    "_shortName": "fileContributor",
    "_userAttributes": {
      "accessAllCollAndUserGroup": true
    }
  },
  {
    "_description": "File Reader",
    "_name": "File Reader",
    "_shortName": "fileReader",
    "_userAttributes": {
      "accessAllCollAndUserGroup": true
    }
  },
  {
    "_description": "Project admin group",
    "_name": "Project admin group",
    "_shortName": "prjAdmin",
    "_userAttributes": {
      "accessAllCollAndUserGroup": true
    }
  }
]

Response

Response codes

Code	Description
`201`	Created
`400`	Bad Request

Response data example

{
  "_offset": 0,
  "_pageSize": 3,
  "_total": 3,
  "_list": [
    {
      "_id": "5785d332-7928-4cf1-867b-6cf7354068a2",
      "_description": "File Contributor",
      "_name": "File Contributor",
      "_shortName": "fileContributor",
      "_namespaces": [
        "fileContributor_JV4m6k9z"
      ],
      "_metadata": {
        "_createdAt": 1561008859862,
        "_updatedAt": 1561008859924,
        "_createdById": "17285382-7f67-4b04-b231-bcdca454ed2c",
        "_updatedById": "17285382-7f67-4b04-b231-bcdca454ed2c",
        "_createdByName": "xxxxxxx",
        "_updatedByName": "xxxxxxx"
      },
      "_userAttributes": {
        "accessAllCollAndUserGroup": true
      },
      "_isMember": true
    },
    {
      "_id": "7fd3507b-1f1b-42fc-ba0a-9f84c920a0e5",
      "_description": "File Reader",
      "_name": "File Reader",
      "_shortName": "fileReader",
      "_namespaces": [
        "fileReader_vYi3Jv4B"
      ],
      "_metadata": {
        "_createdAt": 1561008859920,
        "_updatedAt": 1561008859962,
        "_createdById": "17285382-7f67-4b04-b231-bcdca454ed2c",
        "_updatedById": "17285382-7f67-4b04-b231-bcdca454ed2c",
        "_createdByName": "xxxxxxx",
        "_updatedByName": "xxxxxxx"
      },
      "_userAttributes": {
        "accessAllCollAndUserGroup": true
      },
      "_isMember": true
    },
    {
      "_id": "d064184e-f807-4799-907a-ea42c8ba3b82",
      "_description": "Project admin group",
      "_name": "Project admin group",
      "_shortName": "prjAdmin",
      "_namespaces": [
        "prjAdmin_XOPpzlbm"
      ],
      "_metadata": {
        "_createdAt": 1561008859957,
        "_updatedAt": 1561008859984,
        "_createdById": "17285382-7f67-4b04-b231-bcdca454ed2c",
        "_updatedById": "17285382-7f67-4b04-b231-bcdca454ed2c",
        "_createdByName": "xxxxxxx",
        "_updatedByName": "xxxxxxx"
      },
      "_userAttributes": {
        "accessAllCollAndUserGroup": true
      },
      "_isMember": true
    }
  ]
}

Edit User Group

Endpoint

PUT /passportsvc/api/v1/usergroups/{id}

Request

Path parameters

Parameter	Type	Description	Required
`id`	String	The UserGroup's id.	Optional

Request body example

UserUroup object

{
  "_description": "Admin Group",
  "_name": "Admin Group",
  "_shortName": "ag",
  "_userAttributes": {
    "number": 100,
    "privilege": "Supervisor"
  }
}

Response

Response codes

Code	Description
`200`	Success
`403`	Forbidden
`400`	Bad Request

Response data example

{
  "_id": "27515e32-c115-4ed4-846b-9ab443bf69a8",
  "_description": "Admin Group",
  "_name": "Admin Group",
  "_shortName": "ag",
  "_namespaces": [
    "ag_lsrBUvMV"
  ],
  "_userAttributes": {
    "number": 200,
    "privilege": "Supervisor"
  },
  "_metadata": {
    "_createdAt": 1523275922144,
    "_updatedAt": 1523275922162,
    "_createdById": "cfd0bc81-d9b7-4892-a83f-47af96a48c96",
    "_updatedById": "cfd0bc81-d9b7-4892-a83f-47af96a48c96",
    "_createdByName": "xxxxxxx",
    "_updatedByName": "xxxxxxx"
  },
  "_isMember": true
}

Get User Groups

Retrieve all the user groups that the user is a member of by default. Use includeAll as true to retrieve both the user groups of which the user is a part and those for which the user has 'READ' access.

Endpoints

GET /passportsvc/api/v1/usergroups

Request

Body parameters

Parameter	Type	Description	Required
`id`	String	The UserGroup's id.	Optional
`_name`	String	Readable long-form name	Required
`_shortName`	String	An abbreviated name up to 22 characters that is used for reference	Required
`_offset`	String	Page response offset	Optional
`_pageSize`	String	Page response size	Required
`_userType`	String	A user-defined type for the UserGroup that you can use to distinguish or group it by.	Required
`_userAttributes.<attribute_name>`	Object	Query by user attribute property and value, for example, `_userAttributes._name=myUserGroupName`. The _id, _name and _shortName properties accept multiple values, for example, `_shortName=shortname1&_shortName=shortname2`	Optional
`includeAll`	Object	Set to true to retrieve UserGroups that the user has 'READ' access to as well as UserGroups that the user is part of.	Optional
`query`	Object	Wild card search on name, short name and description properties, for example, `?query=admin`.	Optional
`_orgId`	String	Get organization level user groups	Optional

Response

Response codes

Code	Description
`200`	Success

Response data

{
  "_offset": 3,
  "_pageSize": 1,
  "_total": 4,
  "_list": [
  {
    "_id": "19f4056c-84d4-4f14-bb87-65615ab11ce0",
    "_description": "Admin Group",
    "_name": "Admin Group",
    "_shortName": "ag",
    "_namespaces": [
      "ag_kjqrbbGP"
    ],
    "_userAttributes": {
      "number": 200,
      "privilege": "Supervisor"
    },
    "_metadata": {
      "_createdAt": 1523275922144,
      "_updatedAt": 1523275922162,
      "_createdById": "cfd0bc81-d9b7-4892-a83f-47af96a48c96",
      "_updatedById": "cfd0bc81-d9b7-4892-a83f-47af96a48c96",
      "_createdByName": "xxxxxxx",
      "_updatedByName": "xxxxxxx"
    },
    "_isMember": true
  }
]
}

Get User Group By Id

Endpoints

GET /passportsvc/api/v1/usergroups/{id}

Request

Path parameters

Parameter	Type	Description	Required
`id`	String	The UserGroup's id.	Optional

Response

Response codes

Code	Description
`200`	Success
`400`	Bad Request

Response data example

{
  "_id": "27515e32-c115-4ed4-846b-9ab443bf69a8",
  "_description": "Admin Group",
  "_name": "Admin Group",
  "_shortName": "ag",
  "_namespaces": [
    "ag_lsrBUvMV"
  ],
  "_userAttributes": {
    "number": 200,
    "privilege": "Supervisor"
  },
  "_metadata": {
    "_createdAt": 1523275922144,
    "_updatedAt": 1523275922162,
    "_createdById": "cfd0bc81-d9b7-4892-a83f-47af96a48c96",
    "_updatedById": "cfd0bc81-d9b7-4892-a83f-47af96a48c96",
    "_createdByName": "xxxxxxx",
    "_updatedByName": "xxxxxxx"
  },
  "_isMember": true
}

Get Users in User Group

Endpoints

GET /passportsvc/api/v1/usergroups/{id}/users

Request

Path parameters

Parameter	Type	Description	Required
`id`	String	The UserGroup's id.	Optional

Response

Response codes

Code	Description
`200`	Success
`400`	Bad Request

Response data example

{
  "_offset": 0,
  "_pageSize": 2,
  "_total": 2,
  "_list": [
    {
      "_id": "2edbafe9-ca29-4b67-938e-d2c2711fa2f6",
      "_username": "devtest12",
      "_firstname": "Developer12",
      "_lastname": "Test12",
      "_eusa": false,
      "_privacy": false,
      "_type": {
        "accType": "demo"
      },
      "_email": "devtest12@company.com",
      "_socialProfile": {},
      "_isSocial": false
    },
    {
      "_id": "760e5b93-22ed-4d9d-bf1a-b313270ecf62",
      "_username": "xxxxxxx",
      "_firstname": "xxx",
      "_lastname": "xxxx",
      "_eusa": false,
      "_privacy": false,
      "_type": {
        "accType": "demo"
      },
      "_socialUserId": "dbid:AABw1pLvzCuAHGmvWn8WXzH_d4JprHpt_SE",
      "_email": "xxxxxxx@gmail.com",
      "_socialProfile": {
        "socialdata": [
          {
            "provider": "dropbox",
            "data": {
              "name": {
                "surname": "xxx",
                "given_name": "xxxx",
                "display_name": "xxxxxxx",
                "familiar_name": "xxxxxxx",
                "abbreviated_name": "xx"
              },
              "email": "xxxxxxxx@gmail.com",
              "locale": "en-GB",
              "country": "IN",
              "disabled": false,
              "is_paired": false,
              "root_info": {
                ".tag": "user",
                "home_namespace_id": "2303258944",
                "root_namespace_id": "2303258944"
              },
              "account_id": "dbid:AABw1pLvzCuAHGmvWn8WXzH_d4JprHpt_SE",
              "account_type": {
                ".tag": "basic"
              },
              "referral_link": "https://db.tt/FrukYW4wFO",
              "email_verified": true
            }
          }
        ]
      },
      "_isSocial": true
    }
  ]
}

Add Users to User Group

Endpoints

POST /passportsvc/api/v1/usergroups/{id}/users

Request

Path parameters

Parameter	Type	Description	Required
`id`	String	The UserGroup's id.	Optional

Body example

Array of user ids

[
  "14e63426-e664-44bc-a85e-697fbf00b01f" ,
  "650d9886-3534-445c-b514-0f0a426078a9",
  "cfd0bc81-d9b7-4892-a83f-47af96a48c96"
]

Response

Response codes

Code	Description
`200`	Success
`400`	Bad Request
`403`	Forbidden

Response data example

[
  {
    "_id": "14e63426-e664-44bc-a85e-697fbf00b01f",
    "_username": "doe",
    "_firstname": "john",
    "_lastname": "doe",
    "_eusa": false,
    "_privacy": false,
    "_type": {
      "accType": "demo"
    },
    "_email": "doe8@company.com",
    "_isSocial": false
  },
  {
    "_id": "650d9886-3534-445c-b514-0f0a426078a9",
    "_username": "xxxxxxx",
    "_firstname": "xxx",
    "_lastname": "xxxx",
    "_eusa": false,
    "_privacy": false,
    "_type": {
      "accType": "demo"
    },
    "_socialUserId": "_nkRQEpYvo",
    "_email": "xxxxxxx@gmail.com",
    "_socialProfile": {
      "socialdata": [
        {
          "provider": "linkedin",
          "data": {
            "id": "_nkRQEpYvo",
            "lastName": "xxx",
            "firstName": "xxxx",
            "emailAddress": "xxxxxxx@gmail.com",
            "formattedName": "xxxxxxx"
          }
        }
      ]
    },
    "_isSocial": true
  },
  {
    "_id": "cfd0bc81-d9b7-4892-a83f-47af96a48c96",
    "_username": "doe",
    "_firstname": "john",
    "_lastname": "doe",
    "_eusa": false,
    "_privacy": false,
    "_type": {
      "accType": "demo"
    },
    "_email": "doe4@company.com",
    "_isSocial": false
  }
]

Remove Users from User Group

Endpoints

DELETE /passportsvc/api/v1/usergroups/{id}/users

Request

Path parameters

Parameter	Type	Description	Required
`id`	String	The UserGroup's id.	Optional

Body example

Array of user ids

[
  "14e63426-e664-44bc-a85e-697fbf00b01f" ,
  "650d9886-3534-445c-b514-0f0a426078a9",
  "cfd0bc81-d9b7-4892-a83f-47af96a48c96"
]

Response

Response codes

Code	Description
`204`	No Content
`400`	Bad Request
`403`	Forbidden

Response data

None

Delete User Group

Endpoints

DELETE /passportsvc/api/v1/usergroups/{id}

Request

Path parameters

Parameter	Type	Description	Required
`id`	String	The UserGroup's id.	Optional

Response

Response codes

Code	Description
`204`	No Content

Response data

None

Create User Group Invites

Endpoints

POST /passportsvc/api/v1/usergroups/{id}invites

Request

Path parameters

Parameter	Type	Description	Required
`id`	String	The UserGroup's id.	Optional

Body parameters

Parameter	Type	Description	Required
`_email`	String	The invited user's email	Required
`_params`	String	Placeholder values to be replaced in the email template
`_params.invite_link`	String	Relative path of the callback URL the invitee clicks in the email. The web app's base URL must be registered with Passport Sservice and prepended while sending the notification.
`_params.type`	String	Type of inviting entity for example, a project or account.
`_params.name`	String	The name of inviting entity.
`_params.inviter_name`	String	The inviter's name.
`_params.base_url`	String	Web app's base URL.	Required
`_params.locale`	String	The language locale value to use in notification templates. If you do not pass a value, the default value of en (English) is used.

[
  {
    "_email": "alice@mailinator.com",
    "_params": {
      "base_url": "https://xxxxxxxxxx.com",
      "invite_link": "/digitaltwin",
      "type": "Project",
      "name": "Kingspan IKON",
      "inviter_name": "Srinivas SP",
      "body_header": "",
      "body_content": "Srinivas SP has invited you to join the Project Kingspan IKON.",
      "subject": "Invitation to join  Project: Kingspan IKON",
      "locale": "en"
    }
  }
]

Response

Response codes

Code	Description	Example
`201`	Created
`400`	Bad Request
`403`	Forbidden	The user doesn't have 'EDIT' permission for the UserGroup

Response data example

{
  "_offset": 0,
  "_pageSize": 1,
  "_total": 1,
  "_list": [
    {
      "_email": "alice@mailinator.com",
      "_expireTime": 1662970445947,
      "_id": "5b5aaff4-e146-41f1-8987-41968f0f9c47",
      "_userExists": false,
      "_params": {
        "base_url": "https://xxxxxxxxxx.com",
        "invite_link": "https://xxxxxxxxxx.com/digitaltwin?inviteId=5b5aaff4-e146-41f1-8987-41968f0f9c47",
        "type": "Project",
        "name": "Kingspan IKON",
        "inviter_name": "Srinivas SP",
        "body_header": "",
        "body_content": "Srinivas SP has invited you to join the Project Kingspan IKON.",
        "subject": "Invitation to join  Project: Kingspan IKON",
        "host": "https://xxxxxxxxxx.com/passportsvc/api",
        "fromUserName": "Srinivas SP",
        "APP_ID": "0f02c817-8655-423e-9d22-5439187078f9"
      },
      "_usergroup": {
        "_id": "c24f70fd-d8ea-45d1-bdca-03d437811020",
        "_description": "Solutions User Group",
        "_name": "Solutions Mgmt",
        "_shortName": "sol_man",
        "_namespaces": [
          "solman_feuQqHSZ"
        ],
        "_metadata": {
          "_createdAt": 1566234364029,
          "_updatedAt": 1566234408713,
          "_createdById": "6a8d7971-a2c6-428d-8ef7-0ba604366f2f",
          "_updatedById": "6a8d7971-a2c6-428d-8ef7-0ba604366f2f"
        },
        "_userAttributes": {
          "userConfigs": [
            {
              "_id": "5d5ad728240bc05d81d4c040",
              "_name": "DBM Solution Admin"
            }
          ],
          "permissions": {
            "accessAll": true
          },
          "project": {
            "_id": "d7083dd6-329c-4123-943c-a7a2fbddf7dd",
            "_namespaces": [
              "ks_weG9Hlxk"
            ]
          },
          "UserConfig": [
            "5d5ad728240bc05d81d4c040"
          ]
        },
        "_userType": "user_group",
        "_isMember": true,
        "_appId": "0f02c817-8655-423e-9d22-5439187078f9"
      },
      "_status": "PENDING",
      "_metadata": {
        "_createdAt": 1662365645949,
        "_updatedAt": 1662365645949,
        "_createdById": "cf512118-f08c-4bfd-98d2-76a3ef6f6876",
        "_updatedById": "cf512118-f08c-4bfd-98d2-76a3ef6f6876"
      }
    }
  ]
}

Add Users to User Group By Invite Id

Endpoints

POST /passportsvc/api/v1/usergroups/{id}/users?inviteId={inviteId}

Request

Path parameters

Parameter	Type	Description	Required
`id`	String	The UserGroup's id.	Optional

Query parameters

Parameter	Type	Description	Required
`inviteId`	String	The Invite's id.	Optional

Response

Response codes

Code	Description	Example
`200`	Success
`400`	Bad Request	The email in the Invite doesn't match the current user's email; the UserGroup id doesn't match the UserGroup id in the request

Response data example

[
  {
    "_id": "e6743e65-c67b-4220-aa4f-e440424a66ad",
    "_username": "doe",
    "_firstname": "john",
    "_lastname": "doe",
    "_eusa": false,
    "_privacy": false,
    "_type": {
      "accType": "demo"
    },
    "_email": "john100@company.com",
    "_isSocial": false
  }
]

Get Invites for User Group

Endpoints

GET /passportsvc/api/v1/usergroups/{id}/invites

Request

Path parameters

Parameter	Type	Description	Required
`id`	String	The UserGroup's id.	Optional

Query parameters

Parameter	Type	Description	Required
`_status`	String	Filter by the following invite statuses: `PENDING`, `EXPIRED`, `ACCEPTED`, `CANCELLED`, `REJECTED`	Optional

GET /passportsvc/api/v1/usergroups/{id}/invites?_status=PENDING

Response

Response codes

Code	Description	Example
`200`	Success
`403`	Not Authorized	The user doesn't have READ permission to the UserGroup

Response data example

{
  "_offset": 0,
  "_pageSize": 1,
  "_total": 1,
  "_list": [
    {
      "_email": "xxxxxxx@gmail.com",
      "_expireTime": 1592303525337,
      "_id": "ecf7793c-60ce-4a7a-bb24-b567313f304f",
      "_userExists": true,
      "_params": {
        "inviter_name": "xxxxxxx",
        "name": "FreshProj",
        "base_url": "https://dt-dev.xxxxxx.com",
        "type": "Project",
        "invite_link": "/ipa-dt/"
      },
      "_usergroup": {
        "_id": "35aba78e-6d95-4e79-a210-5e1bc91f98a5",
        "_description": "Solutions User Group",
        "_name": "Solutions Mgmt",
        "_shortName": "sol_man",
        "_namespaces": [
          "solman_58n9eCL5"
        ],
        "_metadata": {
          "_createdAt": 1591683481978,
          "_updatedAt": 1591683794793,
          "_createdById": "bd292f15-10b1-429f-a0ed-b61c56c7c866",
          "_updatedById": "bd292f15-10b1-429f-a0ed-b61c56c7c866"
        },
        "_userType": "user_group",
        "_isMember": true
      },
      "_status": "ACCEPTED",
      "_metadata": {
        "_createdAt": 1591698725347,
        "_updatedAt": 1591699611950,
        "_createdById": "bd292f15-10b1-429f-a0ed-b61c56c7c866",
        "_updatedById": "67b24ac1-3f8b-46ae-9161-35e147d554b7"
      }
    }
  ]
}

Reject or Cancel User Group Invite

Endpoint

PUT /passportsvc/api/v1/usergroups/{id}/invites/{inviteId}

Request

Path parameters

Parameter	Type	Description	Required
`id`	String	The UserGroup's id.	Optional
`inviteId`	String	The Invite's id.	Optional

Body parameters

Parameter	Type	Description	Required
`_status`	String	Either `REJECTED` or `CANCELLED`	Optional

Response

Response codes

Code	Description	Example
`204`	No Content
`400`	Bad Request	Such as status is not in PENDING state
`403`	Unauthorized	principal user, and invitee should be same

Response data

None

Add User Groups​

Endpoints​

Request​

Body example​

Response​

Response codes​

Response data example​

Edit User Group​

Endpoint​

Request​

Path parameters​

Request body example​

Response​

Response codes​

Response data example​

Get User Groups​

Endpoints​

Request​

Body parameters​

Response​

Response codes​

Response data​

Get User Group By Id​

Endpoints​

Request​

Path parameters​

Response​

Response codes​

Response data example​

Get Users in User Group​

Endpoints​

Request​

Path parameters​

Response​

Response codes​

Response data example​

Add Users to User Group​

Endpoints​

Request​

Path parameters​

Body example​

Response​

Response codes​

Response data example​

Remove Users from User Group​

Endpoints​

Request​

Path parameters​

Body example​

Response​

Response codes​

Response data​

Delete User Group​

Endpoints​

Request​

Path parameters​

Response​

Response codes​

Response data​

Create User Group Invites​

Endpoints​

Request​

Path parameters​

Body parameters​

Response​

Response codes​

Response data example​

Add Users to User Group By Invite Id​

Endpoints​

Request​

Path parameters​

Query parameters​

Response​

Response codes​

Response data example​

Get Invites for User Group​

Endpoints​

Request​

Path parameters​

Query parameters​

Add User Groups

Endpoints

Request

Body example

Response

Response codes

Response data example

Edit User Group

Endpoint

Request

Path parameters

Request body example

Response

Response codes

Response data example

Get User Groups

Endpoints

Request

Body parameters

Response

Response codes

Response data

Get User Group By Id

Endpoints

Request

Path parameters

Response

Response codes

Response data example

Get Users in User Group

Endpoints

Request

Path parameters

Response

Response codes

Response data example

Add Users to User Group

Endpoints

Request

Path parameters

Body example

Response

Response codes

Response data example

Remove Users from User Group

Endpoints

Request

Path parameters

Body example

Response

Response codes

Response data

Delete User Group

Endpoints

Request

Path parameters

Response

Response codes

Response data

Create User Group Invites

Endpoints

Request

Path parameters

Body parameters

Response

Response codes

Response data example

Add Users to User Group By Invite Id

Endpoints

Request

Path parameters

Query parameters

Response

Response codes

Response data example

Get Invites for User Group

Endpoints

Request

Path parameters

Query parameters