====================
Connect to the API
====================

Before you can access data with the Energy API you first need to set up authentication.
The API uses access tokens to verify a user. A bearer token is generated by submitting a :http:method:`POST` request 
containing your StormGeo portal login credentials in the request's body, to the login endpoint.
The access token is a required field for requests made to all other endpoints. 

.. important::

  The access token will be valid for 60 minutes from when you submit
  a login request.

Authentication
--------------
.. _authentication:

The following post request will return an access token.

.. http:post:: /api/v1/auth
   :noindex:
   
    Request a bearer token to access the API.

    **Note**: You should replace *username* and *password* with your stromgeo username and password.

    :Content-Type: application/json
    :form: 
        .. sourcecode:: json

            {
              "username": "string",
              "password": "string"
            }


**Example Request**

.. tabs::

    .. tab:: cURL
    
      .. sourcecode:: bash
        
        curl --location --request POST 'https://energy-api.stormgeo.com/api/v1/auth' \
          --header 'Content-Type: application/json' \
          --data-raw '{
          "username": "<your-username>",
          "password": "<your-password>"
          }' 

    .. tab:: csharp
    
        .. code-block:: csharp

            const string url = "https://energy-api.stormgeo.com/api/v1/Auth";
            var client = new HttpClient();
            var content = new StringContent("{\"username\":\"<your-username>\",\"password\":\"<your-password>\"}"
                , Encoding.UTF8, "application/json");
    
            var response = await client.PostAsync(url, content);
            
            var responseString = await response.Content.ReadAsStringAsync();
            
            Console.WriteLine($"{responseString}");

    .. tab:: javascript
    
      .. code-block:: javascript
    
        var myHeaders = new Headers();
        myHeaders.append("Content-Type", "application/json");
        
        var raw = JSON.stringify({
          "username": "<your-username>",
          "password": "<your-password>"
        });
        
        var requestOptions = {
          method: 'POST',
          headers: myHeaders,
          body: raw,
          redirect: 'follow'
        };
        
        fetch("https://energy-api.stormgeo.com/api/v1/auth", requestOptions)
          .then(response => response.text())
          .then(result => console.log(result))
          .catch(error => console.log('error', error));
    
    .. tab:: python
    
      .. code-block:: python
    
        import requests
        
        url = "https://energy-api.stormgeo.com/api/v1/auth"
        headers = {
           "Content-Type": "application/json"
        }
        data = {
            "username": "<your-username>",
            "password": "<your-password>"
        }
        
        response = requests.post(url, headers=headers, json=data)
        print(response.text)


**Example Response**

.. sourcecode:: text

    "bearer_token"