Management

These are a collection of endpoints that allow you to deal with user management.

Endpoints

POST /api/v1/settings/usermanagement/globally_enforce_2fa/disable

POST /api/v1/settings/usermanagement/globally_enforce_2fa/enable

POST /api/v1/user/add

POST /api/v1/user/disable

POST /api/v1/user/edit

POST /api/v1/user/edit/access_level

POST /api/v1/user/enable

POST /api/v1/user/2fa/disable

POST /api/v1/user/flock/assign

POST /api/v1/user/flock/unassign

POST /api/v1/user/note/add

DELETE /api/v1/user/note/delete

POST /api/v1/user/password/reset

POST /api/v1/user/remove

POST /api/v1/user/webauthn/disable

POST /api/v1/user/summary_email/disable

POST /api/v1/user/summary_email/enable

2FA

Currently, we support TOTP and WebAuthn as Two-factor Authentication methods. Enforcing users to use one of these is a great way to ensure that extra bit of security for your users.

Disable Globally Enforcing 2FA

POST /api/v1/settings/usermanagement/globally_enforce_2fa/disable

Do not force users to use 2FA when logging into your Console.

Required Parameters

auth_token string

A valid auth token

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/usermanagement/globally_enforce_2fa/disable \
  -d auth_token=EXAMPLE_AUTH_TOKEN 

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/settings/usermanagement/globally_enforce_2fa/disable'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "result": "success"
}

Enable Globally Enforcing 2FA

POST /api/v1/settings/usermanagement/globally_enforce_2fa/enable

Force users to use 2FA when logging into your Console.

Required Parameters

auth_token string

A valid auth token

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/usermanagement/globally_enforce_2fa/enable \
  -d auth_token=EXAMPLE_AUTH_TOKEN 

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/settings/usermanagement/globally_enforce_2fa/enable'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "result": "success"
}

Add User

POST /api/v1/user/add

Add a new user to your Console.

Required Parameters

auth_token string

A valid auth token

email string

The email address of the user to be added

access_level string

The user access level of the user. Either 'admin' or 'user'

Optional Parameters

totp_enabled boolean

Whether to enable two-factor authentication for this user or not

note string

A text string for storing information related to the user

send_welcome_mail boolean

Defaults to: true

Whether to send the user an email with the login link or not

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/user/add \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d email=EXAMPLE_USER_EMAIL \
  -d access_level=user

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/user/add'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'email': 'EXAMPLE_USER_EMAIL',
  'access_level': 'user'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "msg": "User (<user_email>) successfully created.",
  "result": "success"
}

Add User Note

POST /api/v1/user/note/add

Add a note to a user.

Required Parameters

auth_token string

A valid auth token

email string

The email address of the user

note string

A text string for storing information related to the user

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/user/note/add \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d email=EXAMPLE_USER_EMAIL \
  -d note=EXAMPLE_NOTE

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/user/note/add'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'email': 'EXAMPLE_USER_EMAIL',
  'note': 'EXAMPLE_NOTE'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "msg": "User (<user_email>) note successfully added.",
  "result": "success"
}

Assign User to Flocks

POST /api/v1/user/flock/assign

Assign a user to one or more flocks.

Required Parameters

auth_token string

A valid auth token

email string

The email address of the user

flock_id_list string

A comma separated list of the flocks the user should be assigned (1 or more)

flock_access_level string

The type of privileges the user should have (Either 'manager' or 'watcher')

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/user/flock/assign \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d email=EXAMPLE_USER_EMAIL \
  -d flock_id_list='flock:default,EXAMPLE_FLOCK_ID' \
  -d flock_access_level=watcher

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/user/flock/assign'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'email': 'EXAMPLE_USER_EMAIL',
  'flock_id_list': 'flock:default,EXAMPLE_FLOCK_ID',
  'flock_access_level': 'watcher'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "msg":"User <user_email> successfully assigned to watcher flock(s) [u'flock:default', u'<flock_id>']",
  "result":"success"
}

Disable User

POST /api/v1/user/disable

Disables a specified user. This user will not be able to login. Also disables weekly summary mails.

Required Parameters

auth_token string

A valid auth token

email string

The email address of the user to be disabled

Response

Example

curl https://EXAMPLE.canary.tools/api/v1/user/disable \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d email=EXAMPLE_USER_EMAIL 

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/user/disable'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'email': 'EXAMPLE_USER_EMAIL'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "msg": "User (<user_email>) successfully disabled.",
  "result": "success"
}

Disable User's TOTP

TIP

This is useful for when a user loses access to their Two Factor authentication app (for example losing their phone) and cannot log in to the Console. Temporarily disabling their TOTP will allow them to log back into the Console and reset it.

POST /api/v1/user/2fa/disable

Disables TOTP for a specified user.

Required Parameters

auth_token string

A valid auth token

email string

The email address of the user

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/user/2fa/disable \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d email=EXAMPLE_USER_EMAIL 

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/user/2fa/disable'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'email': 'EXAMPLE_USER_EMAIL'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "msg": "Successfully disabled two-factor authentication for user <user_email>",
  "result": "success"
}

Disable User's WebAuthn

TIP

This is useful for when a user loses access to their WebAuthn authenticator (for example losing their YubiKey) and cannot log in to the Console. Temporarily disabling their WebAuthn will allow them to log back into the Console and reset it.

POST /api/v1/user/webauthn/disable

Disable WebAuthn for a specified user.

Required Parameters

auth_token string

A valid auth token

email string

The email address of the user to be removed

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/user/webauthn/disable \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d email=EXAMPLE_USER_EMAIL 

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/user/webauthn/disable'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'email': 'EXAMPLE_USER_EMAIL'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "result": "success"
}

Disable User Summary Email

TIP

Users can disable summary emails for themselves. Disabling summary emails for another user requires a global admin account.

POST /api/v1/user/summary_email/disable

Disables summary email notifications for a specified user.

Required Parameters

auth_token string

A valid auth token

email string

The email address of the user whose summary emails should be disabled

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/user/summary_email/disable \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d email=EXAMPLE_USER_EMAIL

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/user/summary_email/disable'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'email': 'EXAMPLE_USER_EMAIL'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "msg": "Successfully disabled summary email for email <user_email>",
  "result": "success"
}

Edit User

POST /api/v1/user/edit

Edits a specified user.

Required Parameters

auth_token string

A valid auth token

email string

The email address of the user to be edited

Optional Parameters

note string

A text string for storing information related to the user

Response

Example

curl https://EXAMPLE.canary.tools/api/v1/user/edit \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d email=EXAMPLE_USER_EMAIL \
  -d note='Example note'

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/user/edit'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'email': 'EXAMPLE_USER_EMAIL',
  'note': 'Example note'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "msg": "User (<user_email>) successfully edited.",
  "result": "success"
}

Edit User Access Level

POST /api/v1/user/edit/access_level

Edits a user's access level.

Required Parameters

auth_token string

A valid auth token

email string

The email address of the user to be edited

access_level string

Access level to change to (Either 'admin' or 'user')

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/user/edit/access_level \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d email=EXAMPLE_USER_EMAIL \
  -d access_level=admin

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/user/edit/access_level'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'email': 'EXAMPLE_USER_EMAIL',
  'access_level': 'admin'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "result": "success"
}

Enable User

POST /api/v1/user/enable

Enables a specified user. This user will be able to login if previously disabled. Also enables weekly summary mails.

Required Parameters

auth_token string

A valid auth token

email string

The email address of the user to be enabled

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/user/enable \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d email=EXAMPLE_USER_EMAIL 

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/user/enable'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'email': 'EXAMPLE_USER_EMAIL'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "msg": "User (<user_email>) successfully enabled.",
  "result": "success"
}

Enable User Summary Email

TIP

Users can enable summary emails for themselves. Enabling summary emails for another user requires a global admin account.

POST /api/v1/user/summary_email/enable

Enables summary email notifications for a specified user.

Required Parameters

auth_token string

A valid auth token

email string

The email address of the user whose summary emails should be enabled

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/user/summary_email/enable \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d email=EXAMPLE_USER_EMAIL

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/user/summary_email/enable'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'email': 'EXAMPLE_USER_EMAIL'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "msg": "Successfully enabled summary email for email <user_email>",
  "result": "success"
}

Remove User

POST /api/v1/user/remove

Remove a user from the Console.

Required Parameters

auth_token string

A valid auth token

email string

The email address of the user to be removed

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/user/remove \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d email=EXAMPLE_USER_EMAIL 

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/user/remove'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'email': 'EXAMPLE_USER_EMAIL'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "msg": "User (<user_email>) successfully removed.",
  "result": "success"
}

Remove User from Flocks

POST /api/v1/user/flock/unassign

Remove a user to one or more flocks.

Required Parameters

auth_token string

A valid auth token

email string

The email address of the user

flock_id_list string

A comma separated list of the flocks the user should be removed from (1 or more)

flock_access_level string

The type of privileges the user should have (Either 'manager' or 'watcher')

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/user/flock/unassign \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d email=EXAMPLE_USER_EMAIL \
  -d flock_id_list='flock:default,EXAMPLE_FLOCK_ID' \
  -d flock_access_level=manager

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/user/flock/unassign'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'email': 'EXAMPLE_USER_EMAIL',
  'flock_id_list': 'flock:default,EXAMPLE_FLOCK_ID',
  'flock_access_level': 'manager'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "msg": "User <user_email> successfully unassigned from manager flock(s) [u'flock:default', u'<flock_id>']",
  "result": "success"
}

Remove User Note

DELETE /api/v1/user/note/delete

Remove a user's note.

Required Parameters

auth_token string

A valid auth token

email string

The email address of the user

Response

JSON structure with result indicator.

Example

curl -X DELETE https://EXAMPLE.canary.tools/api/v1/user/note/delete \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d email=EXAMPLE_USER_EMAIL 

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/user/note/delete'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'email': 'EXAMPLE_USER_EMAIL'
}

r = requests.delete(url, data=payload)

print(r.json())

Response

{
  "msg": "User (<user_email>) note successfully removed.",
  "result": "success"
}

Reset User Password

TIP

When resetting a user's password, they'll receive a "Password Reset" email.

POST /api/v1/user/password/reset

Reset a user's password.

Required Parameters

auth_token string

A valid auth token

email string

The email address of the user whose password will be reset

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/user/password/reset \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d email=EXAMPLE_USER_EMAIL 

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/user/password/reset'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'email': 'EXAMPLE_USER_EMAIL'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "msg": "Password reset email sent to <user_email>",
  "result": "success"
}