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:

Login to Backend Admin: Access the Django admin interface
Navigate to OAuth2 Section: Go to the OAuth2/Application Tokens section
Create Token for User: Generate a new token for the specific user account
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:

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:

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:

Access the Django admin panel
Navigate to the OAuth2/Application Tokens section
Create a new token for the desired user account
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:

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

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

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

Security Best Practices

Secure token storage: Store tokens in environment variables or secure credential management systems
HTTPS only: Always use HTTPS for API requests in production
Token rotation: Consider rotating tokens periodically for enhanced security
Access logging: Monitor API access logs for unusual activity
Error handling: Implement proper error handling for authentication failures
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:

// 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:

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:

# 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"