Manage your staff, invite new users, assign system roles
TABLE OF CONTENTS |
User Management
Create a user
POST /v1/b2b/customer/users
(Requires Admin Permissions)
Pass the email address and password in the headers as x-acme-email and x-acme-password. An email will be sent to the email address specified with a link for them to click to confirm the account.
Invite a user
POST /v1/b2b/customer/users/invite
(Requires Admin Permissions)
email list is passed into a request header 'email_invites'
Get list of users by role
GET /v1/b2b/customer/users
Query Parameters: All are optional
- pageSize: Number of entries to return
- page: Which page you are getting
- departmentId: Filter, only return users for this department
- roleId: Filter, only return users with this role
- jobTitle: Filter only return users with this title in their title.
- activeOnly: if true then will not return deactivated users.
Get a user
GET /v1/b2b/customer/users/id/{userId}Input
userId: the id of the user you are looking for.
Response
The User Object corresponding to the user you requested.
Update a user
PUT /v1/b2b/customer/users/{userId}Note: If you pass a password in then you must also pass in an old password to change the password.
Body
A User Object
Input
userId: the id of the user you are updating.
Response
The resulting User object
Password Management
Recover Password
GET /v1/b2b/customer/users/recoverPassword
Recover Password flow, call this function with an email address in the headers and an email will be sent to that address with a link that contains a token to recover the password. Pass the email address in as header x-acme-email in the request headers.
Input
x-acme-email: (Header) the email address to recover the password for.
Finish Recovering a password
GET /v1/b2b/customer/users/recoverFinish
Second part of the recover password flow, after the user has typed in a new password send it to this url in the headers with the token used to recover the password. This will change the user's password to the new password and return a session that they can use. Pass token in the header as x-acme-token and the new password in the header as x-acme-password.
Input
x-acme-token: (Header) the token that was emailed to the user.
x-acme-password: (Header) the new password.
Response
A User Session Object
Admin set password
PUT /v1/b2b/customer/users/{userId}/passwordThe body is simply the new password for the specified user. Changes the password for the user to that specified.
Confirming Users
Confirm a user
GET /v1/b2b/customer/users/confirm
Token must be passed in as x-acme-token
Input
x-acme-token: (Header) the token that was emailed to the user to confirm their account.
Response
A User Session Object
Resend confirmation
POST /v1/b2b/customer/users/{userId}/resendConfirmationResend the confirmation email to the specified user.
confirmationToken will be different than previously sent tokens.
If the user has been deactivated then this will throw an exception saying the "User is deactivated and can not be invited"
if the user has already onboarded we will throw an exception saying "User is already on boarded, please recover password if forgotten."
Input
userId: The id of the user to resend the confirmation for.
Managing Departments, Roles and Titles
Batch Update Departments
PUT /v1/b2b/customer/users/departments/{departmentId}The body will be a list of userIds that you want assigned to that department.
Body
A list of user ids to assign to the department
Input
departmentId: The id of the department to assign the users to.
Response
None
Batch Update Roles
PUT /v1/b2b/customer/users/permissions/{roleId}The body will be a list of userIds that you want this role assigned to.
Body
A list of user id's to assign the role to.
Input
roleId: The id of the role you are adding to the users.
Response
None
Get Existing Titles
GET /v1/b2b/customer/users/titles
Returns
a list of the existing titles.
Get Existing Roles
GET /v1/b2b/customer/users/permissions
Returns
a list of the existing roles Role Objects
Objects
User Object
Field | Description |
|---|---|
| id | The unique id of the user. |
| tenantId | The id of the tenant that the user belongs to. |
| Email address for the user. | |
| firstName | First name of the user. |
| lastName | Last name, family name, of the user. |
| phoneNumber | User's phone number. |
| title | Job title for the user. |
| streetAddress1 | First line in the address of the user. |
| streetAddress2 | Second line in the address of the user. |
| city | The city of the user. |
| state | The state/province of the user. |
| zipCode | The user's zip/postal code. |
| country | The country of the user. |
| confirmed | True if the user has confirmed their email address. |
| onBoarded | True if the user has been onboarded. |
| department | The name of the department that the user is in. (Read Only) |
| departmentId | The id of the department that the user is in. |
| userName | User name for the user. |
| active | true if the user is active, false if they've been deactivated |
| status |
|
| password | required for create and for changing password. If you pass this in an update user call then you must also provide an oldPassword. Write Only) |
| oldPassword | Leave empty unless you are changing the password. (Write Only) |
Role Object
Field | Description |
|---|---|
| id | The unique id of the role. |
| name | The name of the role. |
| permissions | A list of permissions for the role. |