User Service Reference
======================

.. http:post:: https://users.authentise.com/users/

    Create a new user.

    :<json string email: **Required.** The first email address of the user
    :<json string name: **Required.** The name of the user
    :<json string password: **Required.** The raw text of the password for the user. This will not be stored by the server so remember it
    :<json string username: **Required.** The username of the user. This is used for authenticating and uniquely identifying the user
    :<json string address: **Optional.** The address of the user. This is used for tracking where a user lives.
    :<json string company: **Optional.** The company the user is apart of. This is used for identifying specific users in a company

    :>header Location: The URI of the user that was created

    **Example request**

    .. sourcecode:: javascript

        POST https://users.authentise.com/users/
        Content-Type: application/json

        {
            "email"     : "kenny@powers.com",
            "name"      : "Kenny Powers",
            "password"  : "kpow-was-here",
            "username"  : "kpowers",
            "address"   : "kpowers house",
            "company"   : "Jefferson Davis Middle School",
        }
        Location: https://users.authentise.com/users/25a6307b-ca76-43fb-924c-6252c133adcd/


.. http:get:: https://users.authentise.com/users/<uuid>/

    Get information about a user.

    :>json string email: The first email address of the user
    :>json string name: The name of the user
    :>json string password: The raw text of the password for the user. This will not be stored by the server so remember it
    :>json string username: The username of the user. This is used for authenticating and uniquely identifying the user
    :<json string address:  The address of the user. This is used for tracking where a user lives.
    :<json string company:  The company the user is apart of. This is used for identifying specific users in a company

    **Example response**

    .. sourcecode:: javascript

        GET https://users.authentise.com/users/25a6307b-ca76-43fb-924c-6252c133adcd/
        Content-Type: application/json

        {
            "address"   : "kpowers house",
            "name"      : "Kenny Powers",
            "password"  : "kpow-was-here",
            "username"  : "kpowers",
            "company"   : "Jefferson Davis Middle School",
            "uri"       : "https://users.authentise.com/users/25a6307b-ca76-43fb-924c-6252c133adcd/",
        }

.. http:post:: https://users.authentise.com/groups/

    Create a new group

    :<json string name: The name of the group
    :<json string description: A description of the group

    :>header Location: The URI of the user that was created

    **Example request**

    .. sourcecode:: javascript

        POST https://users.authentise.com/groups/
        Content-Type: application/json

        {
            "description"   : "Sports talk show",
            "name"          : "The Sports Sesh",
        }

        Location: https://users.authentise.com/gropus/f74003ad-9942-42fc-b68c-2ce115baf472

.. http:get:: https://users.authentise.com/groups/<uuid>

    Get information about a group

    :>json string name: The name of the group
    :>json string description: A description of the group
    :>json string uuid: The uuid of the group. This should be turned into a URI

    **Example response**

    .. sourcecode:: javascript

        GET https://users.authentise.com/groups/f74003ad-9942-42fc-b68c-2ce115baf472
        Content-Type: application/json

        {
            "description"   : "Sports talk show",
            "name"          : "The Sports Sesh",
            "uuid"          : "f74003ad-9942-42fc-b68c-2ce115baf472"
        }

.. http:post:: https://users.authentise.com/permissions/

    Create a new permission. A permission ties a user or group (called a ``holder``) to an arbitrary object via a namespace and a right. Namespaces allow different services to avoid collisions and only query on their own rights. From the standpoint of the service each of these properties is a meaningless string.

    :<json string holder: **Required**. The URI of the object that holds the right, usually a group or user
    :<json string namespace: **Required**. The namespace of the permission, usually identifies the service that will respect the permission
    :<json string object: **Required**. The URI of the object on which to grant permission
    :<json string right: **Required**. The right the permission grants. This may frequently be something like ``create`` or ``delete`` but may be any string that has meaning to the service
    :>header Location: The URI of the permission that was created

    **Example request**

    .. sourcecode:: javascript

        POST https://users.authentise.com/permissions/
        Content-Type: application/json

        {
            "holder"        : "https://users.authentise.com/users/6f9ba4a0-bc52-4884-9491-a4dc29768163",
            "namespace"     : "models",
            "object"        : "https://models.authentise.com/models/b507828d-9473-4702-a0c5-6fe737ad2d8d/",
            "right"         : "frombulate"
        }

        Location: https://users.authentise.com/permissions/c688d4cc-0c5b-4200-af39-bca6fa3573a3/

.. http:get:: https://users.authentise.com/permissions/<uuid>/

    Get information about a permission

    :>json string holder: The URI of the object that holds the right, usually a group or user
    :>json string namespace: The namespace of the permission, usually identifies the service that will respect the permission
    :<json string object: The URI of the object on which to grant permission
    :<json string right: The right the permission grants. This may frequently be somethign liek ``create`` or ``delete`` but may be any string that has meaning to the service

    **Example Response**

    .. sourcecode:: javascript

        GET https: https://users.authentise.com/permissions/c688d4cc-0c5b-4200-af39-bca6fa3573a3/
        Content-Type: application/json

        {
            "holder"    : "https://users.authentise.com/users/e8afa9ad-1415-4d84-ad54-4f61c22d985d",
            "namespace" : "models",
            "object"    : "https://models.authentise.com/models/b8409033-d381-4bb1-bd90-b95d2a1a389c",
            "right"     : "frombulate",
            "uri"       : "https://users.authentise.com/permissions/c688d4cc-0c5b-4200-af39-bca6fa3573a3/"
        }

.. http:post:: https://users.authentise.com/memberships/

    Add a user to a group

    :<json string group: **Required** The URI of the group to add a member to
    :<json string user:  **Required** The URI of the user to add to the group

    :>header Location: The URI of the membership that was created

.. http:get:: https://users.authentise.com/memberships/<uuid>/

    Get information about a membership

    :<json string group: The URI of the group this membership is for
    :<json string user:  The URI of the user this membership is for

.. sourcecode:: javascript

    POST https://users.authentise.com/sessions/
    Content-Type: application/json

    {
        "username"  : "EliRibble",
        "password"  : "my-secret",
    }