API Authentication¶

ALwrity uses API key authentication to secure access to all endpoints. This guide explains how to authenticate your requests and manage your API keys.

Authentication Methods¶

API Key Authentication¶

ALwrity uses Bearer token authentication with API keys. Include your API key in the Authorization header of all requests.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://your-domain.com/api/blog-writer

Header Format¶

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Getting Your API Key¶

1. Access the Dashboard¶

Sign in to your ALwrity account
Navigate to the API section
Click "Generate API Key"

2. Generate New Key¶

{
  "name": "My Application",
  "description": "API key for my content management app",
  "permissions": ["read", "write"],
  "expires": "2024-12-31"
}

3. Store Securely¶

Never expose API keys in client-side code
Use environment variables for storage
Rotate keys regularly
Monitor usage for security

API Key Management¶

Key Properties¶

{
  "id": "key_123456789",
  "name": "My Application",
  "key": "alwrity_sk_...",
  "permissions": ["read", "write"],
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-12-31T23:59:59Z",
  "last_used": "2024-01-20T14:22:00Z",
  "usage_count": 1250
}

Permissions¶

Permission	Description
`read`	Read access to content and analytics
`write`	Create and update content
`admin`	Full administrative access

Key Rotation¶

# Create new key
curl -X POST "https://your-domain.com/api/keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Key",
    "permissions": ["read", "write"]
  }'

# Revoke old key
curl -X DELETE "https://your-domain.com/api/keys/old_key_id" \
  -H "Authorization: Bearer YOUR_API_KEY"

Rate Limiting¶

Rate Limits by Plan¶

Plan	Requests per Minute	Requests per Day
Free	10	100
Basic	60	1,000
Pro	300	10,000
Enterprise	1,000	100,000

Rate Limit Headers¶

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1640995200

Handling Rate Limits¶

import time
import requests

def make_request_with_retry(url, headers, data):
    max_retries = 3
    retry_delay = 1

    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=data)

        if response.status_code == 429:  # Rate limited
            retry_after = int(response.headers.get('Retry-After', retry_delay))
            time.sleep(retry_after)
            retry_delay *= 2  # Exponential backoff
        else:
            return response

    raise Exception("Max retries exceeded")

Error Handling¶

Authentication Errors¶

Invalid API Key¶

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "details": {
      "key_id": "key_123456789"
    }
  }
}

Missing API Key¶

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required for authentication",
    "details": {
      "header": "Authorization: Bearer YOUR_API_KEY"
    }
  }
}

Insufficient Permissions¶

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "API key does not have required permissions",
    "details": {
      "required": ["write"],
      "granted": ["read"]
    }
  }
}

Rate Limit Errors¶

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "details": {
      "limit": 60,
      "remaining": 0,
      "reset_time": "2024-01-15T10:31:00Z"
    }
  }
}

Security Best Practices¶

API Key Security¶

Environment Variables

export ALWRITY_API_KEY="your_api_key_here"

Secure Storage

import os
api_key = os.getenv('ALWRITY_API_KEY')

Key Rotation
Rotate keys every 90 days
Use different keys for different environments
Monitor key usage regularly

Request Security¶

HTTPS Only
Always use HTTPS for API requests
Never send API keys over HTTP
Request Validation
Validate all input data
Sanitize user inputs
Use proper content types
Error Handling
Don't expose sensitive information in errors
Log security events
Monitor for suspicious activity

SDK Authentication¶

Python SDK¶

from alwrity import AlwrityClient

# Initialize client with API key
client = AlwrityClient(api_key="your_api_key_here")

# Or use environment variable
import os
client = AlwrityClient(api_key=os.getenv('ALWRITY_API_KEY'))

JavaScript SDK¶

const AlwrityClient = require('alwrity-js');

// Initialize client with API key
const client = new AlwrityClient('your_api_key_here');

// Or use environment variable
const client = new AlwrityClient(process.env.ALWRITY_API_KEY);

cURL Examples¶

# Set API key as environment variable
export ALWRITY_API_KEY="your_api_key_here"

# Use in requests
curl -H "Authorization: Bearer $ALWRITY_API_KEY" \
     -H "Content-Type: application/json" \
     https://your-domain.com/api/blog-writer

Testing Authentication¶

Health Check¶

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://your-domain.com/api/health

Response¶

{
  "status": "healthy",
  "authenticated": true,
  "user_id": "user_123456789",
  "permissions": ["read", "write"],
  "rate_limit": {
    "limit": 60,
    "remaining": 59,
    "reset": 1640995200
  }
}

Troubleshooting¶

Common Issues¶

401 Unauthorized¶

Check API key: Verify key is correct and active
Check format: Ensure proper "Bearer " prefix
Check expiration: Verify key hasn't expired

403 Forbidden¶

Check permissions: Verify key has required permissions
Check scope: Ensure key has access to requested resource

429 Too Many Requests¶

Check rate limits: Verify you're within rate limits
Implement backoff: Use exponential backoff for retries
Upgrade plan: Consider upgrading for higher limits

Getting Help¶

API Documentation: Check endpoint documentation
Support: Contact support for authentication issues
Community: Join developer community for help
Status Page: Check API status for outages

Ready to authenticate your requests? Get your API key and start building with the ALwrity API!