Account users

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

POST /v1/account/users
{
  "name": "James Doe",
  "email": "jamesdoe@acme.com"
  "roles": [
    "rol_1234567890",
    "rol_2345678901"
  ]
}

Response

The Account User object

// account user object
{
  "id": "usr_1234567890",
  ...,
  "roles": [
    "rol_1234567890",
    ...
  ]
}

List users

Retrieve a list of the session.account users.

Request

GET /v1/account/users
?page_size=25&page_index=1&search&filters[status]=active

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.

{
  "list": [ 
    {
      "id": "rec_1234567890",
      ...
    },
    ...
  ],
  "url": "https://api.backstack.com/v1/...",
  "total": 8 
}

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

POST /v1/account/users/:user_id
{
  "roles": [
    "rol_1234567890",
    ...
  ]
}

Response

The Account user object.

// 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

DELETE /v1/account/users/:user_id

Response

The ID of the deleted account user.

{
  "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.

// 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.

// 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.

// 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
}