Authentication & Security

The Tournament Platform uses operator API keys with role-based permissions to provide secure, multi-tenant access to tournament functionality.

API Key Authentication

All Casino Integration APIs require authentication via operator API keys passed in the Authorization header:

GET /api/tournaments
Authorization: Bearer {your-operator-api-key}
Content-Type: application/json

API Key Format

Tournament Platform uses compound API keys with the following format:

Format: pk_xxx:sk_yyy where pk_ is the public key prefix and sk_ is the secret key prefix
Example: pk_1234567890abcdef:sk_9876543210fedcba...
Usage: The full compound key is used in the Authorization header
Security: Keys use SHA256 hashing for authentication validation

Role-Based Permissions

API keys are assigned to operator roles that define specific permissions. This enables fine-grained access control for different use cases.

Available Permissions

Permission	Description	Example Use Case
`tournaments.read`	View tournaments and status	Displaying tournament lists, checking status
`tournaments.write`	Create and update tournaments	Creating scheduled tournaments, updating settings
`tournaments.delete`	Cancel tournaments	Emergency tournament cancellation
`players.read`	View player data and registrations	Displaying participant lists, player stats
`players.write`	Register and manage players	Player registration, rebuy processing
`results.read`	Access results and leaderboard data	Showing leaderboards, final results

Common Role Configurations

Full Access
Tournament Manager
Read Only
Player Registration

All Permissions - For primary integration systems:

{
  "permissions": [
    "tournaments.read",
    "tournaments.write", 
    "tournaments.delete",
    "players.read",
    "players.write",
    "results.read"
  ]
}

Tournament Operations - For tournament management systems:

{
  "permissions": [
    "tournaments.read",
    "tournaments.write",
    "players.read",
    "players.write",
    "results.read"
  ]
}

Monitoring & Reporting - For analytics and reporting systems:

{
  "permissions": [
    "tournaments.read",
    "players.read", 
    "results.read"
  ]
}

Registration System - For player management systems:

{
  "permissions": [
    "tournaments.read",
    "players.read",
    "players.write"
  ]
}

API Key Management

Creating API Keys

Access Operator Dashboard

Log into your Tournament Platform operator dashboard

Navigate to API Keys

Go to Settings → API Keys section

Create New Key

Click “Create API Key” and provide:

Name: Descriptive name for the key
Role: Select appropriate role with required permissions
Expiration: Optional expiration date for security

Copy Key Secret

Important: Copy the key secret immediately - it won’t be shown again

Key Security Best Practices

Never expose API keys in client-side code, public repositories, or logs. Keys should only be used in secure server-to-server communication.

Storage & Environment

Store keys in environment variables or secure credential management systems
Use different keys for development, staging, and production environments
Rotate keys regularly (recommended: every 90 days)
Set expiration dates on keys when possible

Access Control

Use least-privilege principle - grant only necessary permissions
Create separate keys for different systems or purposes
Monitor key usage and disable unused keys
Implement IP whitelist restrictions when possible

Example Environment Configuration

# .env file
TOURNAMENT_API_KEY=pk_1234567890abcdef:sk_9876543210fedcba...
TOURNAMENT_API_BASE_URL=https://ts.playservices.tech/api

// Node.js example
const apiKey = process.env.TOURNAMENT_API_KEY;
const baseUrl = process.env.TOURNAMENT_API_BASE_URL;

const headers = {
  'Authorization': `Bearer ${apiKey}`,
  'Content-Type': 'application/json'
};

Multi-Tenant Security

Operator Isolation

The Tournament Platform provides complete tenant isolation:

Data Scoping: All API responses automatically filtered by operator ID
Resource Access: No cross-operator access to tournaments or players
Configuration Isolation: Independent webhook URLs, settings, and preferences
Audit Trails: Separate audit logs per operator

Request Validation

Every API request undergoes:

API Key Validation: Verify key exists and is active
Permission Check: Ensure key has required permissions for operation
Operator Scoping: Filter all data to operator’s resources only
Rate Limiting: Apply per-operator rate limits
Request Logging: Log all API access for audit purposes

Rate Limiting

Standard Limits

Operation Type	Limit	Window
Tournament Operations	100 requests	per minute
Tournament Creation	10 requests	per minute
Player Registration	200 requests	per minute
Results/Leaderboards	500 requests	per minute
General API Calls	1000 requests	per minute

Rate Limit Headers

API responses include rate limit information:

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642089600

Handling Rate Limits

const makeApiRequest = async (url, options) => {
  const response = await fetch(url, options);
  
  if (response.status === 429) {
    const resetTime = response.headers.get('X-RateLimit-Reset');
    const delay = (resetTime * 1000) - Date.now();
    
    console.log(`Rate limited. Retrying in ${delay}ms`);
    await new Promise(resolve => setTimeout(resolve, delay));
    
    return makeApiRequest(url, options);
  }
  
  return response;
};

Error Handling

All API endpoints return consistent JSON error responses. The platform no longer returns HTML error pages for validation failures.

Authentication Errors

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Common causes:

Invalid or expired API key
Malformed Authorization header
Key not found in system

403 Forbidden

{
  "error": "forbidden", 
  "message": "Insufficient permissions for this operation",
  "code": "INSUFFICIENT_PERMISSIONS",
  "required_permission": "tournaments.write"
}

Common causes:

API key lacks required permission
Attempting to access another operator’s resources
Operation not allowed for key’s role

422 Validation Error

{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."],
    "max_players": ["The max players must be at least 1."],
    "scheduled_start": ["The scheduled start field must be a valid date."]
  }
}

Common causes:

Missing required fields
Invalid data formats
Business rule violations

Security Headers

All API responses include security headers:

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

Testing Authentication

Verify API Key

curl -X GET "https://ts.playservices.tech/api/tournaments" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_9876543210fedcba..." \
  -H "Content-Type: application/json"

Expected Response (200 OK):

{
  "data": [
    {
      "id": "12345",
      "name": "Daily Championship",
      "status": "scheduled",
      "scheduled_start": "2024-01-15T20:00:00Z"
    }
  ],
  "current_page": 1,
  "per_page": 15,
  "total": 1
}

Check Permissions

curl -X GET "https://ts.playservices.tech/api/auth/permissions" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_9876543210fedcba..."

Response:

{
  "operator_id": "op_1234567890abcdef",
  "api_key_id": "key_1234567890abcdef", 
  "permissions": [
    "tournaments.read",
    "tournaments.write",
    "players.read",
    "players.write",
    "results.read"
  ],
  "expires_at": "2024-12-31T23:59:59Z"
}

External APIs

Events & Webhooks

Authentication & Security

Authentication & Security

API Key Authentication

API Key Format

Role-Based Permissions

Available Permissions

Common Role Configurations

API Key Management

Creating API Keys

Key Security Best Practices

Storage & Environment

Access Control

Example Environment Configuration

Multi-Tenant Security

Operator Isolation

Request Validation

Rate Limiting

Standard Limits

Rate Limit Headers

Handling Rate Limits

Error Handling

Authentication Errors

401 Unauthorized

403 Forbidden

422 Validation Error

Security Headers

Testing Authentication

Verify API Key

Check Permissions

Next Steps

Tournament Management

Player Management

​Authentication & Security

​API Key Authentication

​API Key Format

​Role-Based Permissions

​Available Permissions

​Common Role Configurations

​API Key Management

​Creating API Keys

​Key Security Best Practices

​Storage & Environment

​Access Control

​Example Environment Configuration

​Multi-Tenant Security

​Operator Isolation

​Request Validation

​Rate Limiting

​Standard Limits

​Rate Limit Headers

​Handling Rate Limits

​Error Handling

​Authentication Errors

​401 Unauthorized

​403 Forbidden

​422 Validation Error

​Security Headers

​Testing Authentication

​Verify API Key

​Check Permissions

​Next Steps

Tournament Management

Player Management

Authentication & Security

API Key Authentication

API Key Format

Role-Based Permissions

Available Permissions

Common Role Configurations

API Key Management

Creating API Keys

Key Security Best Practices

Storage & Environment

Access Control

Example Environment Configuration

Multi-Tenant Security

Operator Isolation

Request Validation

Rate Limiting

Standard Limits

Rate Limit Headers

Handling Rate Limits

Error Handling

Authentication Errors

401 Unauthorized

403 Forbidden

422 Validation Error

Security Headers

Testing Authentication

Verify API Key

Check Permissions

Next Steps