Appearance
Account Users
DANGER
This document has not been updated since version 0.0.3 and is not ready for production. It will be updated before version 1.0 of the project is released.
Accounts can have many users. Each having different access to resources.
An account user represents the session.user
and the access control privileges provided by the session.account
.
How It Works
When an account adds a new user, a system-generated email is sent to the user with a link to the log-in page.
Prerequisites
Your application must have the log-in URL defined in the dashboard settings. This URL serves as the base endpoint for the link provided in the new user email.
Create A User
Submit the new user data to the API for processing. An activation email is sent to the new user with a link to your log-in page to begin the log-in process.
Request
sh
POST /v1/account/users
{
"name": "James Doe",
"email": "jamesdoe@acme.com"
"roles": [
"rol_1234567890",
"rol_2345678901"
]
}
Parameter | Type | Description |
---|---|---|
name | Required string | The users real name. |
email | Required string | The users email address. |
roles | Optional array | An array of role ids assigned to the user. |
Response
The Account User object
json
// account user object
{
"id": "usr_1234567890",
...,
"roles": [
"rol_1234567890",
...
]
}
List Users
Retrieve a list of the session.account
users.
Request
sh
GET /v1/account/users
?page_size=25&page_index=1&search&filters[status]=active
Parameter | Type | Description |
---|---|---|
page_size | Optional integer | The quantity of records you want returned. The default is 25. |
page_index | Optional integer | The current page index in the array of pages. |
search | Optional string | The value to search for against the specific list. |
filters | Optional array | The filters to apply for the query (e.g. &filters[foo]=bar ). |
Filter | Type | Options |
---|---|---|
status | Optional string | active , pending or deleted . Omit to list all users. |
Response
Returns a list
array of records with the total
records available for the query. The url
of the current request are also included. See the pagination guide for information on paging through lists.
json
{
"list": [
{
"id": "rec_1234567890",
...
},
...
],
"url": "https://api.backstack.com/v1/...",
"total": 8
}
List item property | Type | Description |
---|---|---|
id | String | The user ID. |
created | Integer | The date the relationship was created. |
username | String | The users log-in name. |
name | String | The users real name. Required when creating the relationship. Read-only once the user logs in. |
email | String | The users email address. Required when creating the relationship. Read-only once the user logs in. |
avatar | String | The URL for avatar image uploaded by the user. |
editable | Boolean | Indicates if the system will accept edits on the particular user. |
roles | Array | The role IDs assigned by the account to the user. |
roles_csv | String | The roles assigned to the user in a comma separated string. |
last_login | Integer | The timestamp of the users last log in for the account. |
Update a user
Updates user values that are related to the account relationship. See the user documentation for information on updating the session user.
Request
sh
POST /v1/account/users/:user_id
{
"roles": [
"rol_1234567890",
...
]
}
Parameter | Type | Description |
---|---|---|
name | Optional string | The users real name. This value is updatable until the user is activated. |
email | Optional string | The users email address. This value is updatable until the user is activated. |
resend_email | Boolean | Submitting true will resend the account activation email. This option is available until the user is activated. |
roles | Optional array | An array of role IDs assigned to the user. |
TIP
The API updates only the parameters that are submitted. Submitting an empty value deletes a parameter. If a required value is empty, the existing value is retained.
Response
The Account user object.
json
// account user object
{
"id": "usr_1234567890",
...,
"roles": [
"rol_1234567890",
...
]
}
Delete a user
Deleting an account user does not delete a user from the system. It deletes the account user relationship.
Request
sh
DELETE /v1/account/users/:user_id
Response
The ID of the deleted account user.
json
{
"id": "usr_1234567890"
}
Roles collection
The app schema contains roles relevant to the application version. The roles.distribution[session.account.version_id]
is an array of role IDs and the roles.list
contains the role information.
json
// app schema
{
...
"roles": {
"distribution": {
"ver_1234567890": [
"rol_1234567890",
...
],
...
},
"list": {
"rol_1234567890": {
"title": "Super User",
"description": "The Super User can do anything on the system."
},
...
}
},
...
}
The following logic will provide data for a group of checkboxes when assigning roles.
js
// extracting app schema values for creating role checkboxes
Object.keys(roles.distribution[session.account.version_id]).map((id) => {
console.log({
"name": "roles",
"value": id,
"selected": session.user.roles.includes(id),
"text": roles.distribution[session.account.version_id][id].title + ': ' + roles.distribution[session.account.version_id][id].description
});
});
The Account User object
An object that represents the current relationship between an account and a user.
json
// account user object
{
"id": "usr_1234567890",
"created": 1670636064,
"username": "jamesdoe",
"name": "James Doe",
"email": "jamesdoe@acmecorp.com",
"last_login": 1708348174,
"avatar": "https://cdn.backstack.com/avatars/usr_1234567890.jpg",
"roles": [
"rol_751TqkACiLYbUMDe"
...
],
"roles_csv": "Super User, ...",
"editable": false
}
Property | Type | Description |
---|---|---|
id | String | The user ID. |
created | Integer | The date the relationship was created. |
username | String | The users log-in name. |
name | String | The users real name. Required when creating the relationship. Read-only once the user logs in. |
email | String | The users email address. Required when creating the relationship. Read-only once the user logs in. |
avatar | String | The URL for avatar image uploaded by the user. |
editable | Boolean | Indicates if the system will accept edits on the particular user. |
roles | Array | The role IDs assigned by the account to the user. |
roles_csv | String | The roles assigned to the user in a comma separated string. |
last_login | Integer | The timestamp of the users last log in for the account. |