Get Token
=========

Retrieve an authentication token to access the Crayon API.

Overview
^^^^^^^^

This endpoint authenticates a user and returns an access token that can be used to authorize subsequent API requests.

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

Before requesting a token, ensure you have the following:

- **Client ID** - Identifier created when you register your application. Register at: https://cloudiq.crayon.com/clients/
- **Client Secret** - Secret key created when you register your application. Register at: https://cloudiq.crayon.com/clients/
- **Username** - Username of your API user. Create an API user at: https://cloudiq.crayon.com/users/
- **Password** - Password of your API user.

C#
^^^^^^^^^^^

Using CrayonApiClient SDK
-------------------------

To get a token, first create an instance of **CrayonApiClient**, then call the **Tokens.GetUserToken()** method.

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

	var clientId = "<clientId>";
	var clientSecret = "<clientSecret>";
	var userName = "<username>";
	var password = "<password>";
	var client = new CrayonApiClient("https://api.crayon.com/");

	var token = client.Tokens.GetUserToken(clientId, clientSecret, userName, password).GetData().AccessToken;

Using RestSharp
---------------

.. code-block:: c#
	
	var client = new RestClient("https://api.crayon.com/") {
	    Authenticator = new HttpBasicAuthenticator(clientId, clientSecret)
	};
			
	var request = new RestRequest("/api/v1/connect/token", Method.POST);
	request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
	request.AddParameter("grant_type", "password");
	request.AddParameter("username", userName);
	request.AddParameter("password", password);
	request.AddParameter("scope", "CustomerApi");
	return client.Execute<TokenResponse>(request);

Request
^^^^^^^

Request Syntax
--------------

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

Request Headers
---------------

The following HTTP request headers are required:

+------------------+---------------------------------------+------------------------------------------------------------------+
| Header           | Type                                  | Description                                                      |
+==================+=======================================+==================================================================+
| Authorization    | Basic <base64 encoded string>         | **Required.** Base64 encoded string of ``ClientId:ClientSecret`` |
+------------------+---------------------------------------+------------------------------------------------------------------+
| Content-Type     | application/x-www-form-urlencoded     | **Required.** Specifies the media type of the request body.      |
+------------------+---------------------------------------+------------------------------------------------------------------+
| Accept           | application/json                      | Optional. Specifies the expected response type.                  |
+------------------+---------------------------------------+------------------------------------------------------------------+

Authorization Header Values
---------------------------

+---------------+-----------+-------------------------------------------------------------------------------------------------------------------+
| Name          | Type      | Description                                                                                                       |
+===============+===========+===================================================================================================================+
| clientId      | string    | Identifier created when you register your application. Register at: https://cloudiq.crayon.com/clients/           |
+---------------+-----------+-------------------------------------------------------------------------------------------------------------------+
| clientSecret  | string    | Secret key created when you register your application. Register at: https://cloudiq.crayon.com/clients/           |
+---------------+-----------+-------------------------------------------------------------------------------------------------------------------+

Request Body Parameters
-----------------------

The following parameters must be sent as URL-encoded form data:

+---------------+-----------+-----------------------------------------------------------------------------------------------+
| Name          | Type      | Description                                                                                   |
+===============+===========+===============================================================================================+
| grant_type    | string    | **Required.** Use value ``password``                                                          |
+---------------+-----------+-----------------------------------------------------------------------------------------------+
| username      | string    | **Required.** Username of your API user.                                                      |
+---------------+-----------+-----------------------------------------------------------------------------------------------+
| password      | string    | **Required.** Password of your API user.                                                      |
+---------------+-----------+-----------------------------------------------------------------------------------------------+
| scope         | string    | **Required.** Use value ``CustomerApi``                                                       |
+---------------+-----------+-----------------------------------------------------------------------------------------------+

Request Example
---------------

::

	POST https://api.crayon.com/api/v1/connect/token/
	Accept: application/json 
	Content-Type: application/x-www-form-urlencoded
	Authorization: Basic <base64 encoded ClientId:ClientSecret>

	Body (x-www-form-urlencoded):
	grant_type: password
	username: <username>
	password: <password>
	scope: CustomerApi

Response
^^^^^^^^

If successful, this method returns a **TokenResponse** resource in the response body.

Response Example
----------------

.. code-block:: json

	{
	  "AccessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
	  "IdentityToken": null,
	  "Error": null,
	  "ExpiresIn": 20060,
	  "TokenType": "Bearer",
	  "RefreshToken": null
	}

Response Fields
---------------

+------------------+-----------+---------------------------------------------------------------------------------+
| Field            | Type      | Description                                                                     |
+==================+===========+=================================================================================+
| AccessToken      | string    | The token to use in the Authorization header for subsequent API requests.       |
+------------------+-----------+---------------------------------------------------------------------------------+
| IdentityToken    | string    | Identity token (if applicable).                                                 |
+------------------+-----------+---------------------------------------------------------------------------------+
| Error            | string    | Error message if the request failed; otherwise ``null``.                        |
+------------------+-----------+---------------------------------------------------------------------------------+
| ExpiresIn        | integer   | Token validity duration in seconds.                                             |
+------------------+-----------+---------------------------------------------------------------------------------+
| TokenType        | string    | The type of token issued (typically ``Bearer``).                                |
+------------------+-----------+---------------------------------------------------------------------------------+
| RefreshToken     | string    | Token used to obtain a new access token (if applicable).                        |
+------------------+-----------+---------------------------------------------------------------------------------+

Using the Token
^^^^^^^^^^^^^^^

Once you have obtained an access token, include it in the ``Authorization`` header of subsequent API requests:

::

	Authorization: Bearer <AccessToken>