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 short-hand, pre-determined access policy, a user group is a flexible user policy available to enterprise customers.

User roles:

basic: a limit 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.

http https://api.sheepcrm.com/api/v1/user/full/

Add a user to the database¶

Add or create a user for the database. User accounts are active immediately, we don’t support a future start date.

email: The email address of the user (this will also be their username) required
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

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

http https://api.sheepcrm.com/api/v1/{flock}/user/add/ email=james@sheepcrm.com first_name=James last_name=Webster roles:='["basic", "editor"]' "Authorization: Bearer $API_KEY"
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 update (over write) the roles for the user.

   http https://api.sheepcrm.com/api/v1/{flock}/user/add/ email=james@sheepcrm.com roles:='["basic", "admin"]' "Authorization: Bearer $API_KEY"
   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/"
   }


.. code-block:: http

   http https://api.sheepcrm.com/api/v1/{flock}/user/add/ "Authorization: Bearer $API_KEY" email="e@org.co" roles:='[]'

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:

http https://api.sheepcrm.com/api/v1/{flock}/user/add/ email=james@sheepcrm.com roles:='[]' "Authorization: Bearer $API_KEY"

{
    "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 our Enterprise customers.

User groups and users management are controlled through our standard core API.

Get all user groups¶

http 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.

$ cat user-policy.json |  http PUT https://sheepcrm.com/api/v1/{flock}/user_group/60390dd5eb6926712493f061/ "Authorization: Bearer $API_KEY"

Flock permissions¶

Get the flock permissions for a user¶

http https://api.sheepcrm.com/api/v1/{flock}/flock_permission/61892f129d13abfe98a729c1/ "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.)

http PUT https://api.sheepcrm.com/api/v1/{flock}/flock_permission/61892f129d13abfe98a729c1/ "Authorization: Bearer $API_KEY" 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 user group policy for reviewing form responses

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

Example Policies:¶

Form Response Reviewer

Form Scorer

Team Leader

Manual Process for creating a user group¶

View existing user groups https://sheepcrm.com/example/user_group/
Create new user group
- https://sheepcrm.com/example/user_group/new/
- Give the user group a name user group field and a description
Decide on the policy for this group
- Write the policy as a valid JSON document
- Apply the policy to the user group:
$ cat user-policy.json | http PUT https://sheepcrm.com/api/v1/example/user_group/60390dd5eb6926712493f061/ “Authorization: Bearer $API_KEY”
Decide if the policy needs narrowing further with a scope

Manual Process for adding a user to a user group¶

Add a user using the User Permissions in settings
View existing user groups https://sheepcrm.com/example/flock_permission/
Find the user you want to add to the user group
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)