PyQueue Server implements API key-based authentication with queue-specific permissions. Each API key is associated with specific queues and permission levels, providing secure multi-tenant access.
All API endpoints (except health checks) require authentication via the X-API-Key header.
curl -H "X-API-Key: your-api-key" http://localhost:8000/api/v1/queues- READ: View messages and queue information
- WRITE: Add and update messages
- DELETE: Delete individual messages
- MANAGE: Clear queues and access management operations
- User-specific queues: Each user has full access to their own queues
- Shared queues: Limited access (read-only or write-only) to common queues
- Service accounts: Read-only monitoring access
- Admin access: Wildcard access to all queues
{
"pk_user1_abc123def456": {
"description": "User 1 - Email Service",
"queues": {
"user1_notifications": ["read", "write", "delete", "manage"],
"user1_emails": ["read", "write", "delete", "manage"],
"shared_events": ["read"]
}
}
}| API Key | Description | Access |
|---|---|---|
pk_user1_abc123def456 |
User 1 - Email Service | Full access to user1_* queues, read access to shared_events |
pk_user2_ghi789jkl012 |
User 2 - Order Processing | Full access to user2_* queues, write access to shared_events |
pk_service_mno345pqr678 |
Monitoring Service | Read-only access to user queues |
pk_admin_stu901vwx234 |
Admin Access | Full access to all queues (*) |
pk_dev_12345 |
Development Key | Access to test_queue and dev_queue |
GET /api/v1/auth/me
Headers: X-API-Key: your-api-key
Response:
{
"description": "User 1 - Email Service",
"accessible_queues": ["user1_notifications", "user1_emails", "shared_events"],
"queue_permissions": {...},
"total_accessible_queues": 3
}GET /api/v1/auth/permissions/{queue_name}
Headers: X-API-Key: your-api-key
Response:
{
"queue_name": "user1_notifications",
"has_access": true,
"can_read": true,
"can_write": true,
"can_delete": true,
"can_manage": true
}GET /api/v1/queues
Headers: X-API-Key: your-api-key
Response:
{
"queues": [
{
"queue_name": "user1_notifications",
"message_count": 5,
"available_messages": 3,
"in_flight_messages": 2,
"permissions": ["read", "write", "delete", "manage"]
}
],
"count": 1,
"api_key_description": "User 1 - Email Service"
}POST /api/v1/queues/{queue_name}/messages
Headers: X-API-Key: your-api-key
Content-Type: application/json
{
"message": {
"content": "Hello World",
"timestamp": "2025-08-08T10:30:00"
}
}GET /api/v1/queues/{queue_name}/messages?max_messages=10
Headers: X-API-Key: your-api-keyDELETE /api/v1/queues/{queue_name}/messages/{receipt_handle}
Headers: X-API-Key: your-api-keyDELETE /api/v1/queues/{queue_name}/messages
Headers: X-API-Key: your-api-key{
"detail": "Invalid API key"
}{
"detail": "Access denied: write permission required for queue 'user2_orders'"
}{
"detail": [
{
"type": "missing",
"loc": ["header", "x-api-key"],
"msg": "Field required"
}
]
}- Secure Key Storage: Store API keys in environment variables or encrypted configuration
- Key Rotation: Implement regular API key rotation
- Audit Logging: Log all access attempts with API key information
- Rate Limiting: Add rate limiting per API key
- HTTPS Only: Use HTTPS in production environments
# Alternative to config file
export PYQUEUE_API_KEYS_JSON='{"pk_prod_key": {"description": "Production Key", "queues": {...}}}'# docker-compose.yml
version: '3.8'
services:
pyqueue-server:
build: .
environment:
- PYQUEUE_API_KEYS_JSON_FILE=/run/secrets/api_keys
secrets:
- api_keys
secrets:
api_keys:
file: ./secrets/api_keys.jsonRun the security test suite:
python test_security.pyThis will test:
- API key authentication
- Queue-specific permissions
- Admin access patterns
- Service account restrictions
- User information endpoints
import httpx
class PyQueueClient:
def __init__(self, base_url: str, api_key: str):
self.base_url = base_url
self.headers = {"X-API-Key": api_key}
async def add_message(self, queue_name: str, message: dict):
async with httpx.AsyncClient() as client:
response = await client.post(
f"{self.base_url}/api/v1/queues/{queue_name}/messages",
json={"message": message},
headers=self.headers
)
response.raise_for_status()
return response.json()
# Usage
client = PyQueueClient("http://localhost:8000", "pk_user1_abc123def456")
await client.add_message("user1_notifications", {"content": "Hello"})- 422 Validation Error: Missing
X-API-Keyheader - 401 Unauthorized: Invalid or expired API key
- 403 Forbidden: API key lacks required permission for the queue
- 500 Internal Error: Check server logs for configuration issues