Version: v4.5

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": "[email protected]",      "_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": "[email protected]",      "_socialProfile": {        "socialdata": [          {            "provider": "dropbox",            "data": {              "name": {                "surname": "xxx",                "given_name": "xxxx",                "display_name": "xxxxxxx",                "familiar_name": "xxxxxxx",                "abbreviated_name": "xx"              },              "email": "[email protected]",              "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": "[email protected]",    "_isSocial": false  },  {    "_id": "650d9886-3534-445c-b514-0f0a426078a9",    "_username": "xxxxxxx",    "_firstname": "xxx",    "_lastname": "xxxx",    "_eusa": false,    "_privacy": false,    "_type": {      "accType": "demo"    },    "_socialUserId": "_nkRQEpYvo",    "_email": "[email protected]",    "_socialProfile": {      "socialdata": [        {          "provider": "linkedin",          "data": {            "id": "_nkRQEpYvo",            "lastName": "xxx",            "firstName": "xxxx",            "emailAddress": "[email protected]",            "formattedName": "xxxxxxx"          }        }      ]    },    "_isSocial": true  },  {    "_id": "cfd0bc81-d9b7-4892-a83f-47af96a48c96",    "_username": "doe",    "_firstname": "john",    "_lastname": "doe",    "_eusa": false,    "_privacy": false,    "_type": {      "accType": "demo"    },    "_email": "[email protected]",    "_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": "[email protected]",    "_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": "[email protected]",      "_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": "[email protected]",    "_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": "[email protected]",      "_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