Canary API Docs

# 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

# 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 

  
        Copied!
1
2
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# 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 

  
        Copied!
1
2
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# 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

  
        Copied!
1
2
3
4
Response
{
  "msg": "User (<user_email>) successfully created.",
  "result": "success"
}

  
        Copied!
1
2
3
4

# 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

  
        Copied!
1
2
3
4
Response
{
  "msg": "User (<user_email>) note successfully added.",
  "result": "success"
}

  
        Copied!
1
2
3
4

# 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

  
        Copied!
1
2
3
4
5
Response
{
  "msg":"User <user_email> successfully assigned to watcher flock(s) [u'flock:default', u'<flock_id>']",
  "result":"success"
}

  
        Copied!
1
2
3
4

# Disable User

POST /api/v1/user/disable

Disables a specified user. This user will not be able to login.

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 

  
        Copied!
1
2
3
Response
{
  "msg": "User (<user_email>) successfully disabled.",
  "result": "success"
}

  
        Copied!
1
2
3
4

# 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 

  
        Copied!
1
2
3
Response
{
  "msg": "Successfully disabled two-factor authentication for user <user_email>",
  "result": "success"
}

  
        Copied!
1
2
3
4

# 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 

  
        Copied!
1
2
3
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# 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'

  
        Copied!
1
2
3
4
Response
{
  "msg": "User (<user_email>) successfully edited.",
  "result": "success"
}

  
        Copied!
1
2
3
4

# 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

  
        Copied!
1
2
3
4
Response
{
  "result": "success"
}

  
        Copied!
1
2
3

# Enable User

POST /api/v1/user/enable

Enables a specified user. This user will be able to login if previously disabled.

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 

  
        Copied!
1
2
3
Response
{
  "msg": "User (<user_email>) successfully enabled.",
  "result": "success"
}

  
        Copied!
1
2
3
4

# 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 

  
        Copied!
1
2
3
Response
{
  "msg": "User (<user_email>) successfully removed.",
  "result": "success"
}

  
        Copied!
1
2
3
4

# 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

  
        Copied!
1
2
3
4
5
Response
{
  "msg": "User <user_email> successfully unassigned from manager flock(s) [u'flock:default', u'<flock_id>']",
  "result": "success"
}

  
        Copied!
1
2
3
4

# 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 

  
        Copied!
1
2
3
Response
{
  "msg": "User (<user_email>) note successfully removed.",
  "result": "success"
}

  
        Copied!
1
2
3
4

# 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 

  
        Copied!
1
2
3
Response
{
  "msg": "Password reset email sent to <user_email>",
  "result": "success"
}

  
        Copied!
1
2
3
4

← Queries →