Authentication
==============

Use this section to understand how to authenticate with Salesbox's API.

Base URL
*******

.. code-block:: text

    https://segmentai.salesbox.com.br/api

Authentication Methods
*******************

The API supports authentication via API tokens.

API Token Authentication
----------------------

To authenticate your requests, include your API token in the Authorization header:

.. code-block:: text

    Authorization: Bearer YOUR_API_TOKEN

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

.. code-block:: text

    curl -X GET https://segmentai.salesbox.com.br/api/contacts \
         -H "Authorization: Bearer YOUR_API_TOKEN"

Getting an API Token
******************

1. Log in to your Salesbox account
2. Go to Settings > API Tokens
3. Click "Generate New Token"
4. Give your token a name and select the permissions
5. Copy and save your token securely

Token Security
************

- Keep your API token secure and never share it
- Rotate tokens regularly
- Use different tokens for different applications
- Revoke compromised tokens immediately

Rate Limiting
***********

The API has rate limiting to protect the service:

.. list-table::
   :header-rows: 1

   * - Plan
     - Rate Limit
     - Period
   * - Basic
     - 1000 requests
     - per hour
   * - Professional
     - 5000 requests
     - per hour
   * - Enterprise
     - 10000 requests
     - per hour

When you exceed the rate limit, you'll receive a 429 Too Many Requests response.

Error Responses
************

.. list-table::
   :header-rows: 1

   * - Status Code
     - Description
   * - ``401``
     - Invalid or missing API token
   * - ``403``
     - Valid token but insufficient permissions
   * - ``429``
     - Rate limit exceeded

Example Error Response
------------------

.. code-block:: json

    {
        "error": {
            "code": "unauthorized",
            "message": "Invalid API token provided",
            "status": 401
        }
    }