Users

sheepCRM users are user accounts for those with access to the CRM admin system. (sheepApp or self-service users can only access their own data.) Each user has a “flock” permission record which defines the access rights for that user. There are two types of access control: User Roles and User Permissions. A role is a shorthand, pre-determined access policy; a user group is a flexible user policy available to enterprise customers.

User Roles

Role	Description
basic	A limited read-only user.
editor	A limited read/write user.
staff	Read and write access to all data except settings.
admin	Read and write access to all data.

User Info

Packet with user details and user interface settings:

GET https://api.sheepcrm.com/api/v1/user/full/
Authorization: Bearer $API_KEY

Add a User to the Database

Add or create a user for the database. User accounts are active immediately; we do not support a future start date.

Parameter	Description
email	Required. The email address of the user (this will also be their username).
first_name	Optional (recommended). First name of the user.
last_name	Optional (recommended). Last name of the user.
role	Optional (recommended). basic, editor, staff or admin.
send_email	Optional. Defaults to False. Send an invitation email to the user.
password	Optional and not recommended. Passwords should be chosen by the user through the account activation process.

Note

Creating a user account without a role will only allow the user to authenticate (and nothing else). This operation requires admin permissions.

POST https://api.sheepcrm.com/api/v1/{flock}/user/add/
Authorization: Bearer $API_KEY
Content-Type: application/json

{
    "email": "james@sheepcrm.com",
    "first_name": "James",
    "last_name": "Webster",
    "roles": ["basic", "editor"]
}

HTTP/1.1 201 OK
{
    "data": {
        "roles": ["admin", "editor"],
        "user": {
            "display_value": "james@sheepcrm.com",
            "ref": "/sheepcrm/user/618930e69d13ab0052919e76/"
        },
        "user_groups": []
    },
    "uri": "/example/flock_permission/618930e69d13ab0052919e78/"
}

Change the Roles for a User

The add user endpoint will update a user if they already exist. Sending new roles will overwrite the roles for the user:

POST https://api.sheepcrm.com/api/v1/{flock}/user/add/
Authorization: Bearer $API_KEY
Content-Type: application/json

{
    "email": "james@sheepcrm.com",
    "roles": ["basic", "admin"]
}

HTTP/1.1 200 OK
{
    "data": {
        "roles": ["admin", "basic"],
        "user": {
            "display_value": "james@sheepcrm.com",
            "ref": "/sheepcrm/user/618930e69d13ab0052919e76/"
        },
        "user_groups": []
    },
    "uri": "/example/flock_permission/618930e69d13ab0052919e78/"
}

Suspending or Removing a User

A user can be suspended by removing all their roles for a given database. Sheep user accounts are “global” (the same account and credentials operate across multiple databases, possibly controlled by different organisations). For this reason user accounts cannot be deleted.

Send an empty list of roles to remove access:

POST https://api.sheepcrm.com/api/v1/{flock}/user/add/
Authorization: Bearer $API_KEY
Content-Type: application/json

{
    "email": "james@sheepcrm.com",
    "roles": []
}

HTTP/1.1 200 OK
{
    "data": {
        "roles": [],
        "user": {
            "display_value": "james@sheepcrm.com",
            "ref": "/sheepcrm/user/618930e69d13ab0052919e76/"
        },
        "user_groups": []
    },
    "uri": "/example/flock_permission/618930e69d13ab0052919e78/"
}

User Groups

Custom user groups and security policies can be used for finer grain control. Custom user groups are currently only available to Enterprise customers.

Get all user groups

GET https://api.sheepcrm.com/api/v1/{flock}/user_group/
Authorization: Bearer $API_KEY

Update a user group

The endpoint uses the standard methods. For convenience we recommend creating a JSON file, validating it externally and then PUTting to the user group:

PUT https://api.sheepcrm.com/api/v1/{flock}/user_group/{uid}/
Authorization: Bearer $API_KEY
Content-Type: application/json

(contents of user-policy.json)

Flock Permissions

Get the flock permissions for a user

GET https://api.sheepcrm.com/api/v1/{flock}/flock_permission/{uid}/
Authorization: Bearer $API_KEY

HTTP/1.0 200 OK
{
    "bucket": "{flock}",
    "data": {
        "roles": ["basic"],
        "user": {
            "display_value": "example@test.co",
            "ref": "/sheepcrm/user/61892f129d13abfe98a729bf/"
        },
        "user_groups": [null]
    },
    "display_value": "example@test.co",
    "uri": "/{flock}/flock_permission/61892f129d13abfe98a729c1/"
}

Adding a user group to the flock permissions of a user

Find the URI of the user group, PUT to the flock permission record. User group lists are additive, so adding a group will not replace any existing groups.

PUT https://api.sheepcrm.com/api/v1/{flock}/flock_permission/{uid}/
Authorization: Bearer $API_KEY
Content-Type: application/json

{"user_groups": "/{flock}/user_group/5fe2266080859e32e2cd38d7/"}

HTTP/1.0 200 OK

Policies

A user group policy defines the fine-grained access controls. A policy is a JSON document added to the user group resource.

Example: Form response reviewer policy

{
    "policy": {
        "flow_board": ["GET"],
        "flow_board.cards": ["GET"],
        "form_response": ["GET", "PUT"],
        "form_response.comment": ["POST"],
        "form_response.full": ["GET"]
    }
}

Creating a user group (manual process)

1. View existing user groups at https://sheepcrm.com/example/user_group/
2. Create new user group at https://sheepcrm.com/example/user_group/new/
   • Give the user group a name and a description
3. Decide on the policy for this group
   • Write the policy as a valid JSON document
   • Apply the policy to the user group via the API
4. Decide if the policy needs narrowing further with a scope

Adding a user to a user group (manual process)

1. Add a user using the User Permissions in settings
2. View existing flock permissions at https://sheepcrm.com/example/flock_permission/
3. Find the user you want to add to the user group
4. Add the user group URI (e.g. /example/user_group/60390dd5eb6926712493f061/) to the user_group field (the field will auto-save when the input loses focus)