Create User
===========

Create a user. 

Prerequisites
^^^^^^^^^^^^^

- Credentials as described in :doc:`/getting-started/authentication`

C#
^^

To create user, first instantiate **UserUpsert** and set **UserName** and other basic properties such as **FirstName** and **LastName**.

If you are creating a tenant administrator, then you need to set **TenantAdmin** to true.

Next, get the instance of **CrayonApiClient** and then get the client token using the instance. This client token will be passed when creating the user

Finally, call **Users.Create()** method to create user by passing the token and the instance of **UserUpsert**.

.. code-block:: c#
	:emphasize-lines: 12

	var user = new UserUpsert
	{
		UserName = "myuser@company.com",
		FirstName = "Firstname",
		LastName = "LastName",
		TenantAdmin = true // set true if you are creating a tenant administrator, otherwise not necessary to set
	};

	var client = new CrayonApiClient("http://v1.api.crayon.as/");
	var token = client.Tokens.GetUserToken(clientId, clientSecret, userName, password).GetData().AccessToken;
	var createUserResponse = client.Users.Create(token, user);

	if (createUserResponse.IsSuccessStatusCode)
	{
	    // To set the password
	    var userId = createUserResponse.GetData().Id;
	    client.Users.ChangePassword(token, userId, "newpassword");
	}


Request
^^^^^^^

Request Syntax:

+---------+--------------------------------------------------+
| Method  | Request URI                                      |
+=========+==================================================+
| POST    | *https://api.crayon.com/api/v1/users/*           |
+---------+--------------------------------------------------+

Request Body:

+-------------------+----------------------------------------------+-----------------------------------+
| Name              | Type                                         | Description                       |
+===================+==============================================+===================================+
| user              | :doc:`/resources/User`                       | The user to create                |
+-------------------+----------------------------------------------+-----------------------------------+

User Properties:

+-------------------------+--------------------+----------------+
| Name                    | Type               | Required       |
+=========================+====================+================+
| UserName                | string             | Yes            |
+-------------------------+--------------------+----------------+
| FirstName               | string             | Yes            |
+-------------------------+--------------------+----------------+
| LastName                | string             | Yes            |
+-------------------------+--------------------+----------------+
| TenantAdmin             | string             | No             |
+-------------------------+--------------------+----------------+

Request Headers:

The following HTTP request headers are supported

+------------------+----------------+-----------------------------------------------------------------+
| Header           | Type           | Description                                                     |
+==================+================+=================================================================+
| Authorization    | string         | Required. The authorization token in the form Bearer <token>.   |
+------------------+----------------+----------------------------------------------+------------------+
| Accept           | string         | Specifies the request and response type, "application/json".    |
+------------------+----------------+----------------------------------------------+------------------+
| Content-Type     | string         | Specifies the media type of the resource, "application/json".   |
+------------------+----------------+----------------------------------------------+------------------+


Request Example:

::

	POST $"https://api.crayon.com/api/v1/users/"
	Accept: application/json
	Content-Type: application/json 
	Authorization: Bearer < Token >

.. literalinclude:: /scenarios/_static/UserRequest.json
		:language: json

Response
^^^^^^^^
If successful, this method returns the created user as a :doc:`/resources/User` resource in the response body.

Response Body:

.. literalinclude:: /resources/_static/User.json
		:language: json

Response success and error codes:

Each response comes with an HTTP status code that indicates success or failure and additional debugging information. Use a network trace tool to read this code, error type, and additional parameters.

+--------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Error Codes                    | Description                                                                                                                                                                                                                                                                               |
+================================+===========================================================================================================================================================================================================================================================================================+
| 200 Ok                         | The request has succeeded.                                                                                                                                                                                                                                                                |
+--------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 400 Bad Request                | The request could not be understood by the server due to malformed syntax, missing required properties, properties that couldn't be parsed according to their type (and length). It is a non-retryable error condition. The client should not repeat the request without modifications.   |
+--------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 401 Unauthorized               | The request requires user authentication. If the request already included Authorization credentials, then the 401 (Unauthorized) status code means that authorization has been refused for those credentials. It is a non-retryable error condition.                                      |
+--------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+