.. index:: Users

.. _users:

Users
=====

Collection of :ref:`user <user>` representations.

You create new users by posting to this collection. To see what fields you should post and what errors you can
expect when creating users look at the documentation for the :ref:`user <user>` resource.

Creating user accounts
~~~~~~~~~~~~~~~~~~~~~~
This is the standard way to create new user accounts.
New users will not be able to log in to the site until they have confirmed their email address by clicking a link
contained in an email sent to their address. It is not possible to specify a password when creating an account.
Directly after confirming an account the user will be prompted to set a password.

Creating user accounts is currently restricted to clients authenticating with client credentials.
These clients should use a token that has the ``create_account`` scope. Read more about this in the
:ref:`Obtaining an Access Token for a client` section of the authentication chapter.

.. ifconfig:: show_internal_docs

    .. include:: create-headless-account.rst


Relations
---------

.. relations::
    .. relation::
        :name: item

Reference
---------

.. endpoint:: GET /v1/users

Currently returns an empty resource with an item link

.. endpoint:: POST /v1/users

Create a new user


Examples
--------

.. include:: examples/get-users-example.rst

.. include:: examples/create-account-example.rst

.. ifconfig:: show_internal_docs

    .. include:: examples/create-confirmed-account-example.rst