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

The Zocial API uses Bearer Token authentication for external partners to access the system. This is a simple and secure method for API integration.

Bearer Token Authentication
--------------------------

The primary authentication method for external partners is Bearer Token authentication. This uses long-lived tokens that are generated through the backend admin interface.

Obtaining a Bearer Token
~~~~~~~~~~~~~~~~~~~~~~~

Bearer tokens are generated through the backend admin OAuth2 section:

1. **Login to Backend Admin**: Access the Django admin interface
2. **Navigate to OAuth2 Section**: Go to the OAuth2/Application Tokens section
3. **Create Token for User**: Generate a new token for the specific user account
4. **Copy the Token**: The generated token will be displayed and should be securely stored

**Note**: Tokens are long-lived and should be treated as sensitive credentials. Store them securely and never expose them in client-side code or public repositories.

Using Bearer Tokens
~~~~~~~~~~~~~~~~~~

Include the Bearer token in the Authorization header of your API requests:

.. code-block:: text

   GET /api/campaigns/
   Authorization: Bearer <My_long_lived_token_here>
   Content-Type: application/x-www-form-urlencoded

Example API Request
~~~~~~~~~~~~~~~~~~

Here's an example of how to make an authenticated API request:

.. code-block:: text

   curl -X GET "https://your-domain.com/api/campaigns/" \
     -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
     -H "Content-Type: application/x-www-form-urlencoded"

Token Management
---------------

Token Generation
~~~~~~~~~~~~~~~

Tokens are generated through the backend admin interface:

1. Access the Django admin panel
2. Navigate to the OAuth2/Application Tokens section
3. Create a new token for the desired user account
4. The token will be displayed once and should be copied immediately

Token Security
~~~~~~~~~~~~~

- **Long-lived**: These tokens do not expire automatically
- **Secure storage**: Store tokens in secure environment variables or secure credential storage
- **Access control**: Each token is associated with a specific user account and its permissions
- **Revocation**: Tokens can be revoked through the admin interface if needed

Authentication Errors
--------------------

Common authentication errors and their meanings:

.. code-block:: json

   {
     "error": "invalid_token",
     "error_description": "Invalid or expired token"
   }

.. code-block:: json

   {
     "error": "missing_token",
     "error_description": "Authorization header missing or invalid"
   }

.. code-block:: json

   {
     "error": "insufficient_permissions",
     "error_description": "Token does not have required permissions"
   }

Security Best Practices
----------------------

1. **Secure token storage**: Store tokens in environment variables or secure credential management systems
2. **HTTPS only**: Always use HTTPS for API requests in production
3. **Token rotation**: Consider rotating tokens periodically for enhanced security
4. **Access logging**: Monitor API access logs for unusual activity
5. **Error handling**: Implement proper error handling for authentication failures
6. **Never expose tokens**: Never include tokens in client-side code, logs, or public repositories

Example Implementation
----------------------

Here's an example of how to implement Bearer token authentication in different languages:

**JavaScript/Node.js:**

.. code-block:: javascript

   // API request with Bearer token
   async function apiRequest(endpoint, options = {}) {
     const token = process.env.ZOCIAL_API_TOKEN; // Store in environment variable
     const response = await fetch(`https://your-domain.com/api/${endpoint}`, {
       ...options,
       headers: {
         'Authorization': `Bearer ${token}`,
         'Content-Type': 'application/x-www-form-urlencoded',
         ...options.headers
       }
     });
     
     if (!response.ok) {
       throw new Error(`API request failed: ${response.status}`);
     }
     
     return response.json();
   }

   // Example usage
   const campaigns = await apiRequest('campaigns/');

**Python:**

.. code-block:: python

   import os
   import requests

   def api_request(endpoint, options=None):
       token = os.environ.get('ZOCIAL_API_TOKEN')  # Store in environment variable
       headers = {
           'Authorization': f'Bearer {token}',
           'Content-Type': 'application/x-www-form-urlencoded'
       }
       
       if options:
           headers.update(options.get('headers', {}))
       
       response = requests.get(
           f'https://your-domain.com/api/{endpoint}',
           headers=headers,
           **options
       )
       
       response.raise_for_status()
       return response.json()

   # Example usage
   campaigns = api_request('campaigns/')

**cURL:**

.. code-block:: bash

   # Set token as environment variable
   export ZOCIAL_API_TOKEN="your_token_here"
   
   # Make API request
   curl -X GET "https://your-domain.com/api/campaigns/" \
     -H "Authorization: Bearer $ZOCIAL_API_TOKEN" \
     -H "Content-Type: application/x-www-form-urlencoded"