Self Service Auth
==================



Authenticating a user
---------------------

``/api/v1/$FLOCK/user/auth/``

:POST:
	authenticate a user
:DELETE:
	log out

.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/$FLOCK/user/auth/ email=jim@nasa.gov password=space

	HTTP/1.1 201 CREATED
	{
	    "bearer_token": "1abcdefg:abcedfgh",
	    "connected_flocks": [
	        "example",
	        "example-association",
	    ],
	    "email": "jim@nasa.gov",
	    "first_name": "Jim",
	    "flock_data": {
	        "example": true,
	        "example-association": true,
	    },
	    "last_name": "Lovell",
	    "path_upon_activation": null,
	    "reset_token": null,
	    "reset_token_expiry": "2019-11-13T20:56:00.835000",
	    "session_expiry": "2020-02-25T20:19:59.770000",
	    "status": "active",
	    "username": "1abcdefg"
	}

	http DELETE https://api.sheepcrm.com/api/v1/$FLOCK/user/auth/ Authorization:"Bearer $API_KEY"
	HTTP/1.1 200 OK
	{
	    "status": "ok"
	}

.. note::

	TIP save the username and bearer token as an environment variablea e.g. ``export USERNAME=1abcdefg; export API_KEY=1abcdefg:abcedfgh``
	so you can use them in subsequent calls.

	set your email and password as environment variables, install jq and then you can fetch a fresh token in a single command.

	``export APP_API_KEY=$(http https://api.sheepcrm.com/api/v1/example-association/user/auth/ email=$EMAIL password=$SHEEP_PASSWORD | jq ".bearer_token" | sed 's/"//g')``

Pre-authenticate a user
-----------------------

``/api/v1/$FLOCK/user/preauth/``

Use this to check the existance of an account. Missing accounts will return a 404. Where appropriate an activation code will be sent to the user.

:email:
	The email param is required, the email address must be a valid email address.
:quick:
	Optional param: setting to true is recommended

.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/$FLOCK/user/preauth/ email=james@example.com quick=true

	HTTP/1.0 200 OK
	{
	    "crypt": "$2b$12$hu1BFQBaqRVhLijXu/s5muiFekeYIu6r6jlNnB8NvY6JdiRB341sO",
	    "email": "james@example.com",
	    "first_name": James,
	    "status": "preregistered",
	    "username": "****"
	}


Pre-registering a new user
--------------------------

``/api/v1/$FLOCK/user/preregister/``

This method will pre-register a new user without an account activation process. An active session will be opened but the status of 'preregistered' will limit access.

:email:
	The email param is required, the email address must be a valid email address.
:require_activation:
	Optional: defaults to True, set False to prevent an activation email being sent to the new user.

.. code-block:: http

 	http POST https://api.sheepcrm.com/api/v1/$FLOCK/user/preregister/ email=james@example.com

	HTTP/1.0 200 OK
	{
	    "bearer_token": "~~~",
	    "connected_flocks": [
	        "sheep-app",
	    ],
	    "email": "james@example.com",
	    "first_name": null,
	    "flock_data": {},
	    "last_name": null,
	    "path_upon_activation": null,
	    "reset_token": "~~~",
	    "reset_token_expiry": "2020-05-12T11:53:10.379000",
	    "session_expiry": "2020-05-11T23:53:15.870000",
	    "status": "preregistered",
	    "username": "~~~"
	}


Registering a new user
----------------------

``/api/v1/$FLOCK/user/register/``

:email:
	The email param is required, the email address must be a valid email address.
:terms:
	The user must have accepted the terms and conditions of SheepCRM.

.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/$FLOCK/user/register/ email=new-user@example.com terms=Y

	HTTP/1.1 201 CREATED
	{
	    "email": "new-user@example.com",
	    "status": "created",
	    "username": "f3dc4260b8"
	}

Activate a user
---------------

``/api/v1/$FLOCK/user/activate/``

:token:
	The composite username and activatation token `{username}:{reset token}`

.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/$FLOCK/user/activate/ token=abc:123

	{
	    "bearer_token": "***",
	    "connected_flocks": [
	        "sheep-app",
	        "example"
	    ],
	    "email": "***",
	    "first_name": null,
	    "flock_data": {
	        "person_uri": "/example/person/5eb92c0280859e45bd056133/"
	    },
	    "last_name": null,
	    "path_upon_activation": null,
	    "reset_token": "***",
	    "reset_token_expiry": "2020-05-12T10:42:11.790000",
	    "session_expiry": "2020-05-11T23:19:54.850000",
	    "status": "active",
	    "username": "abc"
	}


Confirm email address but don't activate account
------------------------------------------------


``/api/v1/$FLOCK/user/activate_single/``

.. note::
	despite the name this method does NOT activate the account. The token is confirmed and destoyed but the account status is not changed


:token:
	The composite username and activatation token `{username}:{reset token}`

.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/$FLOCK/user/activate/ token=abc:123

	{
	    "bearer_token": "***",
	    "connected_flocks": [
	        "sheep-app",
	        "example"
	    ],
	    "email": "***",
	    "first_name": null,
	    "flock_data": {
	        "person_uri": "/example/person/5eb92c0280859e45bd056133/"
	    },
	    "last_name": null,
	    "path_upon_activation": null,
	    "reset_token": null,
	    "reset_token_expiry": "2020-05-12T10:42:11.790000",
	    "session_expiry": "2020-05-11T23:19:54.850000",
	    "status": "activation-required",
	    "username": "abc"
	}


.. to do

	``/api/v1/$FLOCK/user/$', 'sheepapi.selfservice.user.useraccount'),``


	``/api/v1/$FLOCK/user/reset/$', 'sheepapi.selfservice.user.reset'),``

	``/api/v1/$FLOCK/user/password/$', 'sheepapi.selfservice.user.set_password_using_token'),``