Manage Users
- Print
- PDF
Manage Users
- Print
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
This API manages tenant users in the system.
Note:
- An identity provider (IdP) is a service that stores and verifies user identity. IdPs are generally cloud-hosted services. User identities have associated identity providers. The default identity provider for any user is "Britive".
- A user can have at least one role. The available roles include TenantAdmin, Auditor, and TenantUser.
- There are two types of users: User and ServiceIdentity.
1. List of Users
This is the latest API for "List of Users".
This API returns the list of users for a tenant. The API returns data in pages and multiple API calls have to be made to return the complete list. The API returns the total number of records that can be used to calculate the number of pages.
| GET | {{url}}/api/users?type=User&page=0&size=20&sort=name,asc&filter=status eq active |
Request Parameters
The request parameters used in this method are shown in the following table:
| Parameter | Description | Data Type | Required |
page | The page number starting from zero. | string | Mandatory |
size | The number of records that are returned. Note: The total number of records can be used to calculate the number of pages. For example, 20. | string | Mandatory |
sort | The column used for sorting the records. | string | Optional |
filter | The filter that can filter the list of users based on name, status, role. The supported operators are 'eq' and 'co'. An example format is given here: name co "Smith" | string | Optional |
includeTags | If this is set to true, tags/group memberships are returned. | string | Optional |
Request Example
An example GET request for retrieving the list of users is shown here.
curl --location --request GET '{{url}}/api/users?type=User&page=0&size=20&sort=name,asc&filter=status%20eq%20active' \
--header 'Authorization: TOKEN {{apiToken}}'Response Example
An example response of the GET request for retrieving the list of users is shown here.
| Status: 200 OK |
{
"count": 145,
"page": 0,
"size": 20,
"sort": "name: ASC",
"filter": "status eq active",
"data": [
{
"adminRoles": [
{
"name": "TenantUser",
"displayName": "User"
}
],
"type": "User",
"created": "2020-10-09T06:33:07Z",
"modified": null,
"email": "bob@britive.com",
"username": "bob1",
"firstName": "Bob",
"lastName": "Smith",
"name": "Bob Smith",
"externalId": null,
"mobile": null,
"phone": null,
"identityProvider": {
"id": "3841rj6ovh5w4ptnlj98",
"name": "Test",
"type": "SAML"
},
"mappedAccounts": [],
"external": false,
"status": "active",
"userId": "5quf9uwsinxswwusfqul"
}
]
}(Deprecated) List of Users
Important Note:
The following API for List of Users is deprecated and will be removed in a future release.
The GET method returns the list of users for a tenant.
If the type parameter is not specified, the system uses the default User type. The other type is ServiceIdentity.
| GET | {{url}}/api/users |
Request Parameters
The request parameters used in this method are shown in the following table:
| Parameter | Description | Data Type | Required |
| type | If the parameter type is not specified, the system uses the parameter type as User. The other type is ServiceIdentity. | string | Optional |
filter | This parameter searches by username with an equality operator as the only supported filter. | string | Optional |
Request Example
An example GET request for retrieving the list of users is shown here.
curl --location --request GET '{{url}}/api/users' \
--header 'Authorization: TOKEN {{apiToken}}'Response Example
An example response of the GET request for retrieving the list of users is shown here.
| Status: 200 OK |
[
{
"adminRoles": [
{
"name": "TenantAdmin",
"displayName": "Admin"
}
],
"type": "User",
"email": "simon@tms.com",
"username": "simon@tms.com",
"firstName": "Simon",
"lastName": "Smith",
"name": "Simon Smith",
"externalId": null,
"mobile": "9999999999",
"identityProvider": {
"id": "1HhvrKWjoFPXvOcbJSDx",
"name": "Britive",
"type": "DEFAULT"
},
"mappedAccounts": [],
"external": false,
"status": "active",
"userId": "IBN5LFwyKnQSs0LvGZk9"
}
]2. Get User Details
The GET method returns the details of a user as indicated by the userId path variable. The User object includes information about the user profile and the identity provider.
| GET | {{url}}/api/users/{{userId}} |
Request Example
An example GET request for retrieving the details of a user is shown here.
curl --location --request GET '{{url}}/api/users/{{userId}}' \
--header 'Authorization: TOKEN {{apiToken}}'Response Example
An example response of the GET request for retrieving the details of a user is shown here.
| Status: 200 OK |
{
"userId": "IBN5LFwyKnQSs0LvGZk9",
"username": "simon@tms.com",
"status": "active",
"statusText": "Active",
"lastName": "Smith",
"firstName": "Simon",
"created": "2019-04-16T10:38:18Z",
"modified": "2020-01-07T04:50:31Z",
"createdBy": 1,
"modifiedBy": 1,
"phone": "8888888888",
"mobile": "9999999999",
"email": "simon@tms.com2",
"deleted": null,
"deletedBy": null,
"type": "User",
"externalId": null,
"description": null,
"name": "Simon Smith",
"mappedAccounts": [],
"attributes": [],
"adminRoles": [
{
"name": "TenantAdmin",
"displayName": "Admin"
}
],
"external": false,
"paps": [
{
"tenantAppId": 388,
"name": "s3",
"description": "",
"status": "active",
"expirationDuration": 3600000,
"extendable": false,
"extensionDuration": 1800000,
"extensionLimit": 1,
"notificationPriorToExpiration": 300000,
"appContainerPapPermissions": [
{
"name": "S3FullAccess",
"type": "role",
"nativeId": null,
"appPermissionId": null,
"description": null,
"permissionScopes": [],
"privileged": false
}
],
"runtimeEnvironmentId": null,
"runtimeTargetAccountId": null,
"environments": [],
"userTagIntegrityChecks": [],
"permissions": [
{
"name": "S3FullAccess",
"type": "role",
"nativeId": null,
"appPermissionId": null,
"description": null,
"permissionScopes": [],
"privileged": false
}
],
"papId": "CpD5V2gvUvU9FGC0HVRw",
"appContainerId": "1l7ycFADKgi7AQbp6qXa",
"scope": [
{
"papScopeId": 227,
"type": "EnvironmentGroup",
"appContainerId": 161,
"value": "r-pak3",
"papId": null
}
],
"integrityChecks": [
{
"integrityCheckId": 575,
"permissionName": "S3FullAccess",
"permissionType": "role",
"succeeded": true,
"environmentId": "123750444551",
"scope": null,
"message": "Success",
"permissionId": 73147,
"appContainerId": 161,
"tenantAppId": 386
},
{
"integrityCheckId": 577,
"permissionName": "S3FullAccess",
"permissionType": "role",
"succeeded": true,
"environmentId": "196226166352",
"scope": null,
"message": null,
"permissionId": 71850,
"appContainerId": 161,
"tenantAppId": 385
},
{
"integrityCheckId": 574,
"permissionName": "S3FullAccess",
"permissionType": "role",
"succeeded": true,
"environmentId": "378563640942",
"scope": null,
"message": null,
"permissionId": 74020,
"appContainerId": 161,
"tenantAppId": 387
},
{
"integrityCheckId": 576,
"permissionName": "S3FullAccess",
"permissionType": "role",
"succeeded": true,
"environmentId": "546836430071",
"scope": null,
"message": null,
"permissionId": 72370,
"appContainerId": 161,
"tenantAppId": 384
},
{
"integrityCheckId": 578,
"permissionName": "S3FullAccess",
"permissionType": "role",
"succeeded": true,
"environmentId": "724271230776",
"scope": null,
"message": null,
"permissionId": 73564,
"appContainerId": 161,
"tenantAppId": 388
}
],
"accountIntegrityChecks": [],
"userTags": [],
"users": [
{
"accessPeriod": null,
"mappedAccounts": [],
"name": "Simon Smith",
"type": "User",
"username": "simon@tms.com",
"status": "active",
"userId": "IBN5LFwyKnQSs0LvGZk9",
"email": "simon@tms.com2"
}
]
}
],
"canChangeOrResetPassword": true,
"identityProvider": {
"id": "1HhvrKWjoFPXvOcbJSDx",
"name": "Britive",
"description": "Default Identity Provider",
"type": "DEFAULT",
"scimProvider": "Generic",
"ssoProvider": "Generic",
"scimEnabled": false,
"samlMetadata": null,
"ssoConfig": null,
"mfaEnabled": false,
"apiToken": null,
"userAttributeScimMappings": [
{
"attributeName": "First Name",
"scimAttributeName": "name.givenName",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
},
{
"attributeName": "Last Name",
"scimAttributeName": "name.familyName",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
},
{
"attributeName": "email",
"scimAttributeName": "emails[type eq \"work\"]",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
},
{
"attributeName": "mobile",
"scimAttributeName": "phoneNumbers[type eq \"mobile\"]",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
},
{
"attributeName": "status",
"scimAttributeName": "active",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
},
{
"attributeName": "username",
"scimAttributeName": "userName",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
}
]
}
}3. Create a New User
The POST method creates a new user.
| POST | {{url}}/api/users |
Request Parameters
The request parameter(s) used in this method are shown in the following table:
| Parameter | Possible Parameter Values | Description | Data Type | Required |
| type |
| If the parameter type is not specified, the system uses the default value User type. | string | Optional |
| identityProvider |
| If the parameter type is not specified, the system uses the default value Britive identity provider. This is applicable for users only. | string | Optional |
| username | Value provided by user. | You have to provide the username parameter value. | string | Mandatory |
| lastName | Value provided by user. | You have to provide the lastName parameter value. | string | Mandatory |
| firstName | Value provided by user. | You have to provide the firstName parameter value. | string | Mandatory |
| Value provided by user. | You have to provide the email parameter value. | string | Mandatory | |
| sharePasswordToUser |
| If the value it true the new user received an email with an initial password. | boolean | Optional |
| emailList |
| you have to provide a list of email ids to send an email with an initial password. | list of strings | Optional |
Note:
The password field is not required in the request if the default identity provider is not selected.
Request Example
An example POST request for creating a new user is shown here.
curl --location --request POST '{{url}}/api/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: TOKEN {{apiToken}}' \
--data-raw '{
"email" : "bob2@acme.com",
"username" : "bob2.smith",
"password": "Idontknow123!",
"lastName" : "Smith",
"firstName" : "Bob",
"mobile" : "9999999999",
"phone" : "8888888888",
"status" : "active",
"adminRoles" : [ {
"name": "TenantAdmin"
} ],
"sharePasswordToUser" : true,
"emailList" : [
"james@acme.com",
"john@acme.com"
]
}'Response Example
An example response of the POST request for creating a new user is shown here.
| Status: 201 OK |
{
"userId": "2bfj25ph6ghrj47dg8pl",
"username": "bob2.smith",
"status": "active",
"statusText": "Active",
"lastName": "Smith",
"firstName": "Bob",
"created": "2020-10-01T07:09:26Z",
"modified": null,
"createdBy": 1,
"modifiedBy": null,
"phone": "8888888888",
"mobile": "9999999999",
"email": "bob2@acme.com",
"deleted": null,
"deletedBy": null,
"type": "User",
"externalId": null,
"description": null,
"name": "Bob Smith",
"mappedAccounts": [],
"attributes": [],
"adminRoles": [
{
"name": "TenantAdmin",
"displayName": "Admin"
}
],
"sharePasswordToUser" : true,
"emailList" : [
"james@acme.com",
"john@acme.com"
],
"external": false,
"paps": [],
"canChangeOrResetPassword": true,
"identityProvider": {
"id": "1HhvrKWjoFPXvOcbJSDx",
"name": "Britive",
"description": "Default Identity Provider",
"type": "DEFAULT",
"scimProvider": "Generic",
"ssoProvider": "Generic",
"scimEnabled": false,
"samlMetadata": null,
"ssoConfig": null,
"mfaEnabled": false,
"apiToken": null,
"userAttributeScimMappings": [
{
"attributeName": "First Name",
"scimAttributeName": "name.givenName",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
},
{
"attributeName": "Last Name",
"scimAttributeName": "name.familyName",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
},
{
"attributeName": "email",
"scimAttributeName": "emails[type eq \"work\"]",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
},
{
"attributeName": "mobile",
"scimAttributeName": "phoneNumbers[type eq \"mobile\"]",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
},
{
"attributeName": "status",
"scimAttributeName": "active",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
},
{
"attributeName": "username",
"scimAttributeName": "userName",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
}
]
}
}4. Update User Details
The PATCH method updates the details of a user as indicated by the userId path variable.
| PATCH | {{url}}/api/users/{{userId}} |
Request Example
An example PATCH request for updating a user is shown here. Enter the required lastname, firstname, mobile, phone, status, and name as parameters in the request.
curl --location --request PATCH '{{url}}/api/users/IBN5LFwyKnQSs0LvGZk9' \
--header 'Content-Type: application/json' \
--header 'Authorization: TOKEN {{apiToken}}' \
--data-raw '{
"lastName" : "Smith2",
"firstName" : "Bob2",
"mobile" : "9999999992",
"phone" : "8888888882",
"status" : "inactive",
"adminRoles" : [ {
"name": "TenantUser"
} ]
}'Response Example
| Status: 204 No Content |
The response has only headers.
Note:
This request does not return a response body. If the parameter is not provided then it returns the 400 error (Bad Request).
5. Enable a User
The POST method enables a user as indicated by the userId path variable.
| POST | {{url}}/api/users/{{userId}}/enabled-statuses |
Request Example
An example POST request for enabling a user is shown here.
curl --location --request POST '{{url}}/api/users/dwepkc6xlxepe2wpe455/enabled-statuses' \
--header 'Authorization: TOKEN {{apiToken}}' Response Example
An example response of the POST request for enabling a user is shown here.
| Status: 200 OK |
{
"userId": "dwepkc6xlxepe2wpe455",
"username": "bob2.smith",
"status": "active",
"statusText": "Active",
"lastName": "Smith",
"firstName": "Bob",
"created": "2020-10-01T09:15:29Z",
"modified": "2020-10-01T09:43:40Z",
"createdBy": 1,
"modifiedBy": 1,
"phone": "8888888888",
"mobile": "9999999999",
"email": "bob3@acme.com",
"deleted": null,
"deletedBy": null,
"type": "User",
"externalId": null,
"description": null,
"name": "Bob Smith",
"mappedAccounts": [],
"attributes": [],
"adminRoles": [
{
"name": "TenantAdmin",
"displayName": "Admin"
}
],
"external": false,
"paps": [],
"canChangeOrResetPassword": true,
"identityProvider": {
"id": "1HhvrKWjoFPXvOcbJSDx",
"name": "Britive",
"description": "Default Identity Provider",
"type": "DEFAULT",
"scimProvider": "Generic",
"ssoProvider": "Generic",
"scimEnabled": false,
"samlMetadata": null,
"ssoConfig": null,
"mfaEnabled": false,
"apiToken": null,
"userAttributeScimMappings": [
{
"attributeName": "First Name",
"scimAttributeName": "name.givenName",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
}
]
}
}6. Enable Users
The POST method enables a list of users, as indicated by the array of userId path variables.
| POST | {{url}}/api/users/enabled-statuses |
Request Example
An example POST request for enabling a list of users is shown here.
curl --location --request POST '{{url}}/api/users/enabled-statuses' \
--header 'Authorization: TOKEN {{apiToken}}' \
--data-raw '{
data=json.dumps("{}")
}'Response Example
| Status: 200 OK |
The response only has headers.
Note:
This request does not return a response body.
7. Disable a User
The POST method disables a user as indicated by the userId path variable.
| POST | {{url}}/api/users/{{userId}}/disabled-statuses |
Request Example
An example POST request for disabling a user is shown here.
curl --location --request POST '{{url}}/api/users/{{userId}}/disabled-statuses' \
--header 'Authorization: TOKEN {{apiToken}}'Response Example
An example response of the POST request for disabling a user is shown here.
| Status: 200 OK |
{
"userId": "dwepkc6xlxepe2wpe455",
"username": "bob2.smith",
"status": "active",
"statusText": "Active",
"lastName": "Smith",
"firstName": "Bob",
"created": "2020-10-01T09:15:29Z",
"modified": "2020-10-01T09:39:31Z",
"createdBy": 1,
"modifiedBy": 1,
"phone": "8888888888",
"mobile": "9999999999",
"email": "bob3@acme.com",
"deleted": null,
"deletedBy": null,
"type": "User",
"externalId": null,
"description": null,
"name": "Bob Smith",
"mappedAccounts": [],
"attributes": [],
"adminRoles": [
{
"name": "TenantAdmin",
"displayName": "Admin"
}
],
"external": false,
"paps": [],
"canChangeOrResetPassword": true,
"identityProvider": {
"id": "1HhvrKWjoFPXvOcbJSDx",
"name": "Britive",
"description": "Default Identity Provider",
"type": "DEFAULT",
"scimProvider": "Generic",
"ssoProvider": "Generic",
"scimEnabled": false,
"samlMetadata": null,
"ssoConfig": null,
"mfaEnabled": false,
"apiToken": null,
"userAttributeScimMappings": [
{
"attributeName": "First Name",
"scimAttributeName": "name.givenName",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
}
]
}
}8. Disable Users
The POST method disables a list of users as indicated by an array of userId path variables.
| POST | {{url}}/api/users/disabled-statuses |
Request Example
An example POST request for disabling a list of users is shown here.
curl --location --request POST '{{url}}/api/users/disabled-statuses' \
--header 'Content-Type: application/json' \
--header 'Authorization: TOKEN {{apiToken}}' \
--data-raw '["dwepkc6xlxepe2wpe455"]'Response Example
An example response of the POST request for disabling a list of users is shown here.
| Status: 200 OK |
[
{
"userId": "dwepkc6xlxepe2wpe455",
"username": "bob2.smith",
"status": "inactive",
"statusText": "Inactive",
"lastName": "Smith",
"firstName": "Bob",
"created": "2020-10-01T09:15:29Z",
"modified": "2020-10-01T10:18:16Z",
"createdBy": 1,
"modifiedBy": 1,
"phone": "8888888888",
"mobile": "9999999999",
"email": "bob3@acme.com",
"deleted": null,
"deletedBy": null,
"type": "User",
"externalId": null,
"description": null,
"name": "Bob Smith",
"mappedAccounts": [],
"attributes": [],
"adminRoles": [
{
"name": "TenantAdmin",
"displayName": "Admin"
}
],
"external": false,
"paps": [],
"canChangeOrResetPassword": true,
"identityProvider": {
"id": "1HhvrKWjoFPXvOcbJSDx",
"name": "Britive",
"description": "Default Identity Provider",
"type": "DEFAULT",
"scimProvider": "Generic",
"ssoProvider": "Generic",
"scimEnabled": false,
"samlMetadata": null,
"ssoConfig": null,
"mfaEnabled": false,
"apiToken": null,
"userAttributeScimMappings": [
{
"attributeName": "First Name",
"scimAttributeName": "name.givenName",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
},
{
"attributeName": "Last Name",
"scimAttributeName": "name.familyName",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
},
{
"attributeName": "email",
"scimAttributeName": "emails[type eq \"work\"]",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
},
{
"attributeName": "mobile",
"scimAttributeName": "phoneNumbers[type eq \"mobile\"]",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
},
{
"attributeName": "status",
"scimAttributeName": "active",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
},
{
"attributeName": "username",
"scimAttributeName": "userName",
"identityProviderId": null,
"attributeId": null,
"builtIn": true
}
]
}
}
]9. Reset User Password
The POST method resets a user's password as indicated by the userId path variable. The password must comply with the Britive password policy.
Note:
According to the Britive password policy, a user's password must contain:
- at least 8 characters
- at least 1 uppercase letter
- at least 1 lowercase letter
- at least 1 digit
- at least 1 symbol
| POST | {{url}}/api/users/{{userId}}/resetpassword |
Note:
If the request parameter sharePasswordToUser is true, the password is shared with the user on their email address. The password is also shared on one or more email addresses specified in the recipients' field.
Request Example
An example POST request for resetting the password is shown here.
curl --location --request POST '{{url}}/api/users/{{userId}}/resetpassword' \
--header 'Content-Type: application/json' \
--header 'Authorization: TOKEN {{apiToken}}' \
--data-raw '{
"password" : "Admin@123$",
"sharePasswordToUser" : true,
"recipients" : [
"user1@britive.com"
]
}'Response Example
| Status: 200 OK |
The response only has headers.
Note:
This request does not return a response body.
10. Reset User Multi-factor Authentication (MFA)
The PATCH method resets a user's Multi-factor Authentication (MFA) as indicated by the userId path variable.
| PATCH | {{url}}/api/users/{{userId}}/resetmfa |
Note: Multi-factor Authentication (MFA) is an authentication mechanism where a user or a resource (such as a computer) needs to provide two or more credentials to authenticate its identity to gain access to a specific resource such as an application.
Request Example
An example PATCH request for resetting a user's MFA is shown here.
curl --location --request PATCH '{{url}}/api/users/dwepkc6xlxepe2wpe455/resetmfa' \
--header 'Authorization: TOKEN {{apiToken}}'Response Example
| Status: 200 OK |
The response only has headers.
Note:
This request does not return a response body.
11. Delete a User
The DELETE method deletes a user as indicated by the userId path variable.
| DELETE | {{url}}/api/users/{{userId}} |
Request Example
An example DELETE request for deleting a user is shown here.
curl --location --request DELETE '{{url}}/api/users/{{userId}}' \
--header 'Authorization: TOKEN {{apiToken}}'Response Example
| Status: 200 OK |
The response only has headers.
Note:
This request does not return a response body.
Was this article helpful?
