Users API

The users API provides access to user accounts on the server.

Regular users can list other users, change their own profile data (such as name, password, etc.) or block themselves. Administrators can modify other users, create new user accounts and execute admin-only tasks such as approving new users.

Note

Group membership for users is managed through api_groups.

List Users

Gets a list of all users.

GET /users

Attribute Type Required Description

subscribe (query) boolean no See api_streaming

curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/users

Example response:

[
  {
    "admin": false,
    "approved": true,
    "blocked": false,
    "created_at": "2021-07-02T06:36:18.817Z",
    "email": "",
    "id": 100,
    "last_login": "2021-07-02T06:37:48.569Z",
    "name": "Guest",
    "state": "normal"
  },
  {
    "admin": true,
    "approved": true,
    "blocked": false,
    "created_at": "2021-07-02T06:36:33.392Z",
    "email": "admin@example.com",
    "id": 1000,
    "last_login": "2021-07-02T06:38:36.549Z",
    "name": "admin",
    "state": "normal"
  },
  {
    "admin": false,
    "approved": true,
    "blocked": false,
    "created_at": "2021-07-02T06:38:37.141Z",
    "email": "alice@example.com",
    "id": 1002,
    "last_login": "",
    "name": "Alice",
    "state": "normal"
  }
]

Single User

Gets info about a single user.

GET /users/:id

Attribute Type Required Description

id (path) integer yes The ID of the user to get subscribe (query) boolean no See api_streaming

curl -H "Private-Token: <access token>" https://canvus.example.com/api/v1/users/1002

Example response:

{
  "admin": false,
  "approved": true,
  "blocked": false,
  "created_at": "2021-07-02T06:38:37.141Z",
  "email": "alice@example.com",
  "id": 1002,
  "last_login": "",
  "name": "Alice",
  "state": "normal"
}

Create User

Creates a new user. You must authenticate as an administrator to use this endpoint.

Tip

Unauthenticated requests can be made to the api_users_register endpoint.

POST /users

Attribute Type Required Description

email string yes Email (used also as the login name) of the user. Email address have to be unique for each user. name string yes Display name of the user password string no Password of the user. If password is missing the server sends password reset email to the user admin boolean no If true, the new user is admin. By default this is false. approved boolean no If true, the new user is initially approved. Default value depends on the server settings blocked boolean no If true, the new user is initially blocked. By default this is false.

curl -X POST -H "Private-Token: <access token>" -d '{"email":"bob@example.com","password":"BBBB","name":"Bob"}' https://canvus.example.com/api/v1/users

Example response:

{
  "admin": false,
  "approved": true,
  "blocked": false,
  "created_at": "2021-07-02T06:38:37.501Z",
  "email": "bob@example.com",
  "id": 1003,
  "last_login": "",
  "name": "Bob",
  "state": "normal"
}

Delete User

Permanently deletes a user. You must authenticate as an administrator to use this endpoint.

DELETE /users/:id

Attribute Type Required Description

id (path) integer yes The ID of the user to get

curl -X DELETE -H "Private-Token: <access token>" https://canvus.example.com/api/v1/users/1003

Register User

Registers a new user account. This endpoint does not require authentication.

On success, this endpoint will send an email with confirmation token to the provided email address.

The new user account is not active until the email address is confirmed.

Tip

Registering new users can be disabled in the server settings.

POST /users/register

Attribute Type Required Description

email string yes Email (used also as the login name) of the user. Email address have to be unique for each user. name string yes Display name of the user password string yes Password of the user admin boolean no If true, the new user is admin. By default this is false. Only admin user can set it to true. approved boolean no Is the user needs approval? Default value depends on the server settings. Only admin user can explicitly set it to true. blocked boolean no If true, the new user is initially blocked. By default this is false.

curl -X POST -d '{"email":"carol@example.com","password":"CCCC","name":"Carol"}' https://canvus.example.com/api/v1/users/register

Example response:

{
  "msg": "Sign-up using a password is not enabled"
}

Approve User

Approves registered user accounts pending approval. You must authenticate as an administrator to use this endpoint.

POST /users/:id/approve

Attribute Type Required Description

id (path) integer yes ID of the user

curl -X POST -H "Private-Token: <access token>" https://canvus.example.com/api/v1/users/1002/approve

Example response:

{
  "admin": false,
  "approved": true,
  "blocked": false,
  "created_at": "2021-07-02T06:38:37.141Z",
  "email": "alice@example.com",
  "id": 1002,
  "last_login": "",
  "name": "Alice",
  "state": "normal"
}

Email Confirmation

Confirms user email address with the token from email. This endpoint does not require authentication.

POST /users/confirm-email

Attribute Type Required Description

token string yes Token from the email

curl -X POST -d '{"token":"AAAAAAAAAAAAAAA"}' https://canvus.example.com/api/v1/users/confirm-email

Example response:

{
  "msg": "Invalid email confirmation token."
}

Change Password

This endpoint allows regular user to change their own password by providing the current and new password.

Administrators can use this endpoint to change passwords of other regular users.

POST /users/:id/password

Attribute Type Required Description

id (path) integer yes ID of the user current_password string yes Old password new_password string yes New password

curl -X POST -H "Private-Token: <access token>" -d '{"current_password":"AAAA","new_password":"BBBB"}' https://canvus.example.com/api/v1/users/1002/password

Example response:

{
  "admin": false,
  "approved": true,
  "blocked": false,
  "created_at": "2021-07-02T06:38:37.141Z",
  "email": "alice@example.com",
  "id": 1002,
  "last_login": "",
  "name": "Alice",
  "state": "normal"
}

Request Password Reset

Sends an email with a password reset token to the email address of the user making the request.

The emailed token must be confirmed through the reset endpoint. This endpoint does not require authentication.

POST /users/password/create-reset-token

Attribute Type Required Description

email string yes Email of the user

curl -X POST -d '{"email":"bob@example.com"}' https://canvus.example.com/api/v1/users/password/create-reset-token

Validate Password Reset Token

Validates a password reset token, but does not consume it. This endpoint is available without authentication.

GET /users/password/validate-reset-token

Attribute Type Required Description

token (query) string yes Token from the email

curl https://canvus.example.com/api/v1/users/password/validate-reset-token?token=AAAAAAAAAAAAAAA

Example response:

{
  "msg": "Invalid token"
}

Reset Password

Resets a user password using the provided token from password reset email. This endpoint is available without authentication.

POST /users/password/reset

Attribute Type Required Description

token string yes Token from the email password string yes New password

curl -X POST -d '{"token":"AAAAAAAAAAAAAAA","password":"DDDD"}' https://canvus.example.com/api/v1/users/password/reset

Example response:

{
  "msg": "Invalid token"
}

Sign In User

Signs the user in and issues an access token. This endpoint is available without authentication.

POST /users/login

Attribute Type Required Description

email string yes User email password string yes User password

curl -X POST -d '{"email":"alice@example.com","password":"BBBB"}' https://canvus.example.com/api/v1/users/login

Example response:

{
  "token": "lmFU9obmM5v4o6jdCXsRW6v5bLD9w47aGIP4eMRnf3A",
  "user": {
    "admin": false,
    "approved": true,
    "blocked": false,
    "created_at": "2021-07-02T06:38:37.141Z",
    "email": "alice@example.com",
    "id": 1002,
    "last_login": "",
    "name": "Alice",
    "state": "normal"
  }
}

Alternatively this endpoint can validate an existing token. If token is valid the token lifetime is prolonged.

Attribute Type Required Description

token string yes Access token

curl -X POST -d '{"token":"z_Ttm-tcFpiadMUR2A_8kQnkOsl6wmcEKplotULC9fk"}' https://canvus.example.com/api/v1/users/login

Example response:

{
  "token": "n8_ZgoRHKnQWJnxdgT7s12jfWH5VGuNzpnps3PGZzwo",
  "user": {
    "admin": false,
    "approved": true,
    "blocked": false,
    "created_at": "2021-07-02T06:38:37.141Z",
    "email": "alice@example.com",
    "id": 1002,
    "last_login": "2021-07-02T06:38:38.722Z",
    "name": "Alice",
    "state": "normal"
  }
}

Sign Out User

Signs the user out by invalidating the provided access token.

POST /users/logout

Attribute Type Required Description

token string no Token to invalidate. If empty the Private-Token is used.

curl -X POST -H "Private-Token: <access token>" -d '{"token":"z_Ttm-tcFpiadMUR2A_8kQnkOsl6wmcEKplotULC9fk"}' https://canvus.example.com/api/v1/users/logout

Block a User

Blocks a user. Blocked users can not sign in. Regular users can only block their own account. Administrators can block any user.

POST /users/:id/block

Attribute Type Required Description

id (path) integer yes ID of the user

curl -X POST -H "Private-Token: <access token>" https://canvus.example.com/api/v1/users/1002/block

Example response:

{
  "admin": false,
  "approved": true,
  "blocked": true,
  "created_at": "2021-07-02T06:38:37.141Z",
  "email": "alice@example.com",
  "id": 1002,
  "last_login": "2021-07-02T06:38:38.744Z",
  "name": "Alice",
  "state": "normal"
}

Unblock a User

Unblocks a user. You must authenticate as an administrator to use this endpoint.

POST /users/:id/unblock

Attribute Type Required Description

id (path) integer yes ID of the user

curl -X POST -H "Private-Token: <access token>" https://canvus.example.com/api/v1/users/1002/unblock

Example response:

{
  "admin": false,
  "approved": true,
  "blocked": false,
  "created_at": "2021-07-02T06:38:37.141Z",
  "email": "alice@example.com",
  "id": 1002,
  "last_login": "2021-07-02T06:38:38.744Z",
  "name": "Alice",
  "state": "normal"
}

Set User Info

Changes user profile data such as name or email. Regular users can change only their own profile and only certain fields, administrators can change all fields of any user.

PATCH /users/:id

Attribute Type Required Description

id (path) integer yes ID of the user email string no Email (used also as the login name) of the user. Email address have to be unique for each user. name string no Display name of the user password string no Password of the user. Admin-only. admin boolean no If true, the user is admin. Admin-only. approved boolean no If true, the user is approved. This can be changed only from false to true. Admin-only. blocked boolean no If true, the user is blocked. need_email_confirmation boolean no If true the user has confirmed email. This can be changed only from false to true. Admin-only.

curl -X PATCH -H "Private-Token: <access token>" -d '{"name":"Alice Cooper"}' https://canvus.example.com/api/v1/users/1002

Example response:

{
  "admin": false,
  "approved": true,
  "blocked": false,
  "created_at": "2021-07-02T06:38:37.141Z",
  "email": "alice@example.com",
  "id": 1002,
  "last_login": "2021-07-02T06:38:38.744Z",
  "name": "Alice Cooper",
  "state": "normal"
}

Implements SAML 2.0 ACS endpoint. Validates a SAML assertion and on success signs in the user and issues access token. SAML sign-in can be disabled in server settings. This endpoint is available without authentication.

POST /users/login/saml

Attribute Type Required Description

inResponseTo string yes Cookie known to the initiator of the request responseXml string yes SAML assertion XML

Users API

List Users

Single User

Create User

Delete User

Register User

Approve User

Email Confirmation

Change Password

Request Password Reset

Validate Password Reset Token

Reset Password

Sign In User

Sign Out User

Block a User

Unblock a User

Set User Info

SAML 2.0 Sign-in