*****************************
API Token Authentication Guide
*****************************

This guide covers the basic scenarios for obtaining and using API tokens for users and resellers in your system.

Token Types
===========

There are two ways to obtain API tokens:

1. **Dynamic Tokens** - Obtained via API endpoints (see sections below). These tokens expire after 24 hours.
2. **Static Tokens** - Permanent tokens that can be obtained from the user interface:

   - **For Users**: Available in the **Admin** section of the UI
   - **For Resellers**: Available in the **Reseller interface**

Static tokens do not expire and can be used for long-term integrations without needing to re-authenticate.

1. Obtaining User Token
=======================

Endpoint
--------

``POST /session.json``

Request Parameters
------------------

Content-Type: ``application/json``

Body::

  {
    "login": "user@example.com",
    "password": "user_password"
  }

Example Request (curl)
----------------------

.. code-block:: bash

   curl -X POST https://XXX-NN.dialer.rocks/a/session.json \
     -H "Content-Type: application/json" \
     -d '{
       "login": "user@example.com",
       "password": "your_password"
     }'

Success Response (200)
----------------------

.. code-block:: json

   {
     "user": {
       "id": 123,
       "blocked": false
     },
     "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
   }

Possible Errors
---------------

- **401** - Invalid login credentials
- **406** - Login denied due to IP restriction
- **500** - Server Error

2. Obtaining Reseller Token
============================

Endpoint
--------

``POST /v1/resellers/login.json``

Request Parameters
------------------

Content-Type: ``application/json``

Body::

  {
    "name": "reseller_name",
    "pass": "reseller_password"
  }

Example Request (curl)
----------------------

.. code-block:: bash

   curl -X POST https://XXX-NN.dialer.rocks/a/v1/resellers/login.json \
     -H "Content-Type: application/json" \
     -d '{
       "name": "reseller_name",
       "pass": "your_password"
     }'

Success Response (200)
----------------------

.. code-block:: json

   {
     "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
     "reseller": {
       "id": 1,
       "name": "reseller_name"
     },
     "user_groups": [],
     "user_balance": 1000.00,
     "version": "1.0.0"
   }

Possible Errors
---------------

- **401** - Invalid ID or Password
- **401** - Your IP is not allowed

3. Using the Token
==================

After obtaining the token, use it in the Authorization header for subsequent requests:

.. code-block:: bash

   curl -X GET https://XXX-NN.dialer.rocks/a/some-endpoint \
     -H "Authorization: Bearer YOUR_TOKEN_HERE"

Important Notes
---------------

1. **Token Lifespan**:

   - Dynamic tokens (obtained via API) expire after 24 hours
   - Static tokens (obtained from UI) do not expire

2. **User Token Contents**:

   - type: 'user'
   - admin
   - id
   - name
   - sms_from
   - user_group_id

3. **Reseller Token Contents**:

   - type: 'reseller'
   - id
   - name

4. **IP Restrictions**:

   - Resellers may have IP address restrictions (checked via settings.allowedIPs parameter)
   - Users may have IP restrictions via regex (allowed_regex parameter in user_group)

4. Logout
=========

Delete User Session
-------------------

``DELETE /session.json``

.. code-block:: bash

   curl -X DELETE https://XXX-NN.dialer.rocks/a/session.json \
     -H "Authorization: Bearer YOUR_TOKEN_HERE"

Reseller Logout
---------------

``GET /v1/resellers/user/logout.json``

.. code-block:: bash

   curl -X GET https://XXX-NN.dialer.rocks/a/v1/resellers/user/logout.json \
     -H "Authorization: Bearer YOUR_TOKEN_HERE"