Skip to content

Authentication and service accounts

Every call to the MultiTaction Canvus REST API runs as a Canvus user. An integration should not borrow a person's account. Give it its own account, grant that account only the canvases it needs, and authenticate with a permanent access token. This page shows how.

Choose a credential

Credential How you get it Lifetime Use it for
Access token Web client (Profile, Access tokens) or POST /users/{id}/access-tokens Until you delete it Scripts, services, bots, any unattended integration
Sign-in token POST /users/login with email and password Expires; see Users Interactive tools and short tests
Shared canvas link Canvas link_permission set to view or edit Until the link permission changes Read or edit one canvas without an account

You send a token in the Private-Token header on every request:

curl -H "Private-Token: YOUR_TOKEN" https://canvus.example.com/api/v1/canvases

What a token can do

  • A token carries the identity and permissions of the user it belongs to. There are no token scopes: limit what an integration can do by limiting what its user can do.
  • An access token does not expire. It stops working when you delete it or delete its user.
  • The server shows the token value once, when you create it. Lists and lookups return only its id, description and created_at. Store the value in your secret store straight away.
  • A user can create and manage tokens for their own account. An administrator can create and manage tokens for any account. The server's reserved built-in accounts, such as Guest, cannot have tokens.
  • Creating a token is recorded in the audit log.

Create a token in the web client

  1. Sign in to the Canvus web client with the account the integration will use.
  2. Open Profile in the sidebar and choose Access tokens.
  3. Type a description that says which integration uses the token, then select Create token.
  4. Copy the token. The web client shows it only once.

To revoke a token, open the same page and select Revoke token next to it.

Set up a service account

A service account is an ordinary Canvus user that you reserve for one integration. The steps below use the API, so you can script them. They need an administrator token.

1. Create the user

curl -X POST \
  -H "Private-Token: ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Integration: meeting bot", "email": "meeting-bot@example.com", "approved": true}' \
  https://canvus.example.com/api/v1/users

Keep the account non-administrator (admin defaults to false). The response contains the new user's id.

Because a service account signs in only with tokens, you can leave out password. What happens next depends on the server's email setup:

  • Email configured: the server emails the address a password-reset link. Use a mailbox you control.
  • Email not configured: the server sets a random password that meets the password policy and returns it once as generated_password. You can discard it, because the integration uses a token.
  • Email configured but the invitation fails: the account is still created, and the response carries email_send_error.

Controlling a wall through /clients needs no administrator rights: any user's access token can open a canvas on a workspace or change its view, provided the client allows API access (rest-api-access=rw). Once someone has opened a canvas on a workspace under their own user account, only that user's token can control the workspace, and administrator tokens are refused too. To keep a signage wall under your integration's control, leave it signed out or sign it in with the service account.

2. Grant access to the canvases it needs

Give the account edit on each canvas it writes to, and view on canvases it only reads:

curl -X POST \
  -H "Private-Token: OWNER_OR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"users": [{"id": 1050, "permission": "edit"}]}' \
  https://canvus.example.com/api/v1/canvases/CANVAS_ID/permissions

Only the entries you send change. To grant a whole folder, use the same body with POST /canvas-folders/{id}/permissions. To manage access for several integrations at once, add the accounts to a group (POST /groups/{id}/members with {"id": USER_ID}) and grant the group instead. See Canvases and Groups.

To withdraw access, send "permission": "removed" for that user or group.

3. Create the token

curl -X POST \
  -H "Private-Token: ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "meeting-bot production"}' \
  https://canvus.example.com/api/v1/users/1050/access-tokens

The response contains plain_token. This is the value the integration sends as Private-Token. It is returned only in this response.

4. Rotate and revoke

To rotate, create a second token, deploy it, then delete the old one:

curl -X DELETE -H "Private-Token: ADMIN_TOKEN" \
  https://canvus.example.com/api/v1/users/1050/access-tokens/TOKEN_ID

Deleting a token ends any ?subscribe stream that uses it. Deleting the user ends all of its streams and invalidates all of its tokens.

Responses that point to a permission problem

  • 401 Unauthorized: the Private-Token header is missing. An invalid or deleted token currently returns 403 with {"msg": "Invalid token"}; see Current behavior.
  • 403 Forbidden: the account lacks permission. A view-only account gets this on writes.
  • 402 Payment Required: the server has no valid license. Non-administrators get 402 on every authenticated call. Canvas content calls return 402 for every account, administrators included.

A canvas whose link_permission is view or edit can be read, or edited, without a token. The server then treats the request as the built-in Guest user. If an administrator has disabled the Guest user, these requests return 401 with "Guest user is disabled". Moving, copying, saving, restoring and changing permissions always need a token. Use links for quick sharing, and use a service account for anything that runs unattended.