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. .. code-block:: http 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. .. code-block:: http 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. .. code-block:: http 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: .. code-block:: http 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 ------------------- .. code-block:: http 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. .. code-block:: http $ 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 ------------------------------------ .. code-block:: http 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.) .. code-block:: http 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 .. code-block:: json "policy": { "flow_board": [ "GET" ], "flow_board.cards": [ "GET" ], "form_response": [ "GET", "PUT" ], "form_response.comment": [ "POST" ], "form_response.full": [ "GET" ] } Example Policies: ----------------- - :download:`Form Response Reviewer ` - :download:`Form Scorer ` - :download:`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)