API Authentication

Overview

FootyCollect API uses token-based authentication provided by Django REST Framework. Each user can have a unique authentication token that must be included in the HTTP headers for protected endpoints.

Authentication Methods

The API supports two authentication methods:

Method	Use Case	Implementation
Token Authentication	API clients, mobile apps	`rest_framework.authentication.TokenAuthentication`
Session Authentication	Browser-based requests	`rest_framework.authentication.SessionAuthentication`

Most API clients should use Token Authentication. Session authentication is primarily for browser-based interactions and the Django admin interface.

Obtaining an Authentication Token

To obtain an authentication token, send a POST request to the token endpoint with your username and password.

Endpoint

POST /api/auth-token/

Request

curl -X POST https://your-domain.com/api/auth-token/ \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'

import requests

url = "https://your-domain.com/api/auth-token/"
data = {
    "username": "your_username",
    "password": "your_password"
}

response = requests.post(url, json=data)
token_data = response.json()
print(token_data["token"])

fetch('https://your-domain.com/api/auth-token/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    username: 'your_username',
    password: 'your_password'
  })
})
.then(response => response.json())
.then(data => console.log(data.token));

Response

Success (200 OK)

{
  "token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"
}

Error (400 Bad Request)

{
  "non_field_errors": [
    "Unable to log in with provided credentials."
  ]
}

Store your authentication token securely. Never expose tokens in client-side code, version control, or public repositories.

Using the Authentication Token

Once you have a token, include it in the Authorization header of your API requests using the Token scheme.

Header Format

Authorization: Token <your-token-here>

Example Requests

curl -X GET https://your-domain.com/api/users/me/ \
  -H "Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"

import requests

url = "https://your-domain.com/api/users/me/"
headers = {
    "Authorization": "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"
}

response = requests.get(url, headers=headers)
user_data = response.json()
print(user_data)

fetch('https://your-domain.com/api/users/me/', {
  method: 'GET',
  headers: {
    'Authorization': 'Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b'
  }
})
.then(response => response.json())
.then(data => console.log(data));

Response

{
  "username": "demo_user",
  "name": "Demo User",
  "url": "https://your-domain.com/api/users/demo_user/"
}

Authentication Errors

Missing Token

If you attempt to access a protected endpoint without a token: Response (401 Unauthorized)

{
  "detail": "Authentication credentials were not provided."
}

Invalid Token

If you provide an invalid or expired token: Response (401 Unauthorized)

{
  "detail": "Invalid token."
}

Insufficient Permissions

If your token is valid but you lack permissions: Response (403 Forbidden)

{
  "detail": "You do not have permission to perform this action."
}

Django Allauth Integration

FootyCollect uses django-allauth for account management, which provides:

Email verification for new accounts
Password reset functionality
Social authentication (Google OAuth)
Multi-factor authentication (MFA) support
Account lockout after failed login attempts

Account Security

The following security measures are enforced:

Feature	Configuration
Email Verification	Mandatory for new accounts (`ACCOUNT_EMAIL_VERIFICATION = "mandatory"`)
Login Rate Limiting	5 failed attempts per 5 minutes (`ACCOUNT_RATE_LIMITS = {"login_failed": "5/5m"}`)
Password Requirements	Minimum 8 characters, not similar to username, not commonly used

API token authentication bypasses some django-allauth features like MFA. For maximum security, ensure tokens are stored securely and rotated regularly.

Token Management

Token Persistence

Tokens are stored in the database and persist until explicitly deleted. Each user has one token that remains valid indefinitely unless revoked.

Regenerating Tokens

To regenerate a token (e.g., if compromised), delete the existing token through the Django admin interface:

Navigate to /admin/authtoken/tokenproxy/
Find the user’s token
Delete it
Obtain a new token via /api/auth-token/

Deleting a token will immediately invalidate all API requests using that token. Ensure your applications are updated with the new token.

Best Practices

Store tokens securely

Use environment variables or secure credential storage
Never commit tokens to version control
Never expose tokens in client-side code
Use HTTPS to prevent token interception

Rotate tokens regularly

Implement token rotation for long-running applications
Regenerate tokens if you suspect compromise
Delete tokens for deactivated users

Handle token expiration gracefully

Implement proper error handling for 401 responses
Provide a mechanism to reauthenticate
Log authentication failures for monitoring

Use HTTPS in production

Always use HTTPS to encrypt token transmission
Configure SECURE_SSL_REDIRECT = True in Django settings
Set appropriate security headers

Example: Complete Authentication Flow

Here’s a complete example demonstrating authentication and API usage:

import requests
from typing import Optional

class FootyCollectClient:
    def __init__(self, base_url: str):
        self.base_url = base_url
        self.token: Optional[str] = None
    
    def authenticate(self, username: str, password: str) -> bool:
        """Obtain authentication token."""
        url = f"{self.base_url}/api/auth-token/"
        response = requests.post(url, json={
            "username": username,
            "password": password
        })
        
        if response.status_code == 200:
            self.token = response.json()["token"]
            return True
        return False
    
    def get_headers(self) -> dict:
        """Get headers with authentication token."""
        if not self.token:
            raise ValueError("Not authenticated. Call authenticate() first.")
        return {"Authorization": f"Token {self.token}"}
    
    def get_current_user(self) -> dict:
        """Get current authenticated user."""
        url = f"{self.base_url}/api/users/me/"
        response = requests.get(url, headers=self.get_headers())
        response.raise_for_status()
        return response.json()

# Usage
client = FootyCollectClient("https://your-domain.com")
if client.authenticate("demo_user", "password123"):
    user = client.get_current_user()
    print(f"Authenticated as: {user['username']}")

#!/bin/bash

# Configuration
BASE_URL="https://your-domain.com"
USERNAME="demo_user"
PASSWORD="password123"

# Obtain token
TOKEN_RESPONSE=$(curl -s -X POST "$BASE_URL/api/auth-token/" \
  -H "Content-Type: application/json" \
  -d '{"username":"'$USERNAME'","password":"'$PASSWORD'"}')

TOKEN=$(echo $TOKEN_RESPONSE | jq -r '.token')

if [ "$TOKEN" == "null" ]; then
  echo "Authentication failed"
  exit 1
fi

echo "Token obtained: $TOKEN"

# Use token to get current user
USER_RESPONSE=$(curl -s -X GET "$BASE_URL/api/users/me/" \
  -H "Authorization: Token $TOKEN")

echo "Current user: $USER_RESPONSE"

Next Steps

Now that you understand authentication, learn about:

Rate Limiting - Understanding API rate limits
API Introduction - Available endpoints and usage

API Overview

Endpoints

FKAPI Integration

Overview

Authentication Methods

Obtaining an Authentication Token

Endpoint

Request

Response

Using the Authentication Token

Header Format

Example Requests

Response

Authentication Errors

Missing Token

Invalid Token

Insufficient Permissions

Django Allauth Integration

Account Security

Token Management

Token Persistence

Regenerating Tokens

Best Practices

Example: Complete Authentication Flow

Next Steps

​Overview

​Authentication Methods

​Obtaining an Authentication Token

​Endpoint

​Request

​Response

​Using the Authentication Token

​Header Format

​Example Requests

​Response

​Authentication Errors

​Missing Token

​Invalid Token

​Insufficient Permissions

​Django Allauth Integration

​Account Security

​Token Management

​Token Persistence

​Regenerating Tokens

​Best Practices

​Example: Complete Authentication Flow

​Next Steps

Overview

Authentication Methods

Obtaining an Authentication Token

Endpoint

Request

Response

Using the Authentication Token

Header Format

Example Requests

Response

Authentication Errors

Missing Token

Invalid Token

Insufficient Permissions

Django Allauth Integration

Account Security

Token Management

Token Persistence

Regenerating Tokens

Best Practices

Example: Complete Authentication Flow

Next Steps