API Keys Management

Learn how to create, manage, and configure your SAPIENTRIS API keys and third-party API integrations for optimal performance and security.

Types of API Keys & Configurations

1. SAPIENTRIS API Keys

Personal API keys for accessing the SAPIENTRIS platform:

Tied to your individual user account
Inherit your personal permissions
Perfect for development and testing
Limited to your account's rate limits

2. Global Third-Party API Configurations (Admin Only)

System-wide API service definitions managed by superadmins:

Define available third-party services (OpenAI, Twitch, etc.)
Set up service templates and validation rules
Configure provider-specific settings
Manage which services are available to users

3. User Third-Party API Keys

Your personal configurations for third-party services:

Use your own API keys for enhanced privacy
Override global configurations with personal credentials
Encrypted storage for security
Per-service activation control

Creating & Managing API Keys

SAPIENTRIS API Keys

Navigate to Dashboard → API Keys
Click Create New API Key
Fill in the required information:
- Name: Descriptive name for the key
- Description: Optional description
- Permissions: Select appropriate access level
- Expiration: Set expiration date (optional)
Click Create API Key
Important: Copy and securely store your API key immediately

User Third-Party API Keys

Configure your personal third-party API keys to enhance SAPIENTRIS functionality:

Navigate to Dashboard → My API Keys
Browse available third-party services
Click Configure for the service you want to set up
Enter your API credentials:
- API Key/Token: Your personal API key
- Additional Settings: Service-specific configuration
- Notes: Optional notes for your reference
Test Connection to verify credentials
Activate the service

Available Third-Party Services

The following services can be configured with your personal API keys:

AI & Language Processing:

OpenAI GPT: For AI-powered content generation and analysis
Anthropic Claude: Advanced language processing and insights
OpenRouter: Multi-model AI access with unified API

Streaming & Social:

Twitch API: Enhanced streamer data and real-time analytics
YouTube Data API: Video content analysis and trend tracking
Google Trends: Market intelligence and search trend analysis

Analytics & Data:

Google Analytics: Website traffic and user behavior insights
Casino Direct APIs: Real-time casino data feeds

API Key Permissions

Read Only

{
  "permissions": [
    "casinos:read",
    "streamers:read", 
    "games:read",
    "analytics:read"
  ]
}

Read/Write

{
  "permissions": [
    "casinos:read",
    "casinos:write",
    "streamers:read",
    "streamers:write",
    "analytics:read"
  ]
}

Admin

{
  "permissions": [
    "*:read",
    "*:write", 
    "*:delete",
    "admin:*"
  ]
}

Custom Permissions

Create fine-grained permissions for specific use cases:

{
  "permissions": [
    "casinos:read",
    "spielhallen:read",
    "german-market:read",
    "compliance:read"
  ]
}

Managing API Keys

Viewing Your Configurations

SAPIENTRIS API Keys

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.sapientris.com/v1/user/api-keys

User Third-Party API Keys

View your configured third-party services:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.sapientris.com/v1/user/third-party-apis

Response:

{
  "data": [
    {
      "service_name": "openai_gpt",
      "display_name": "OpenAI GPT",  
      "provider": "openai",
      "category": "ai",
      "is_active": true,
      "has_user_config": true,
      "last_tested_at": "2024-08-05T14:30:00Z",
      "last_error": null,
      "request_count": 245,
      "usage_stats": {
        "requests_today": 15,
        "requests_month": 245,
        "tokens_used": 125000
      },
      "notes": "Personal OpenAI key for enhanced AI features"
    },
    {
      "service_name": "twitch_api",
      "display_name": "Twitch API",
      "provider": "twitch", 
      "category": "streaming",
      "is_active": false,
      "has_user_config": false,
      "last_tested_at": null,
      "notes": null
    }
  ]
}

Rotating API Keys

For security, regularly rotate your API keys:

Create a new API key with same permissions
Update your applications to use the new key
Monitor usage to ensure transition is complete
Revoke the old API key

Revoking API Keys

curl -X DELETE \
     -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.sapientris.com/v1/user/api-keys/{key_id}

How Third-Party API Integration Works

SAPIENTRIS uses a two-tier system for third-party API integration:

Global Configuration (Admin Level)

Superadmins define which third-party services are available:

{
  "service_name": "openai_gpt",
  "display_name": "OpenAI GPT",
  "provider": "openai",
  "category": "ai",
  "description": "AI-powered content generation and analysis",
  "is_required": false,
  "is_active": true,
  "configuration_template": {
    "api_key": { "required": true, "type": "password" },
    "organization": { "required": false, "type": "text" },
    "model": { "required": false, "type": "text", "default": "gpt-4o" },
    "max_tokens": { "required": false, "type": "number", "default": 4096 }
  }
}

User Configuration (Personal Level)

Users configure their own API keys for each service:

{
  "user_id": 123,
  "service_name": "openai_gpt",
  "configuration": {
    "api_key": "***encrypted:sk-...***",
    "organization": "org-user123",
    "model": "gpt-4o",
    "max_tokens": 2048
  },
  "is_active": true,
  "notes": "Personal OpenAI key for enhanced AI features"
}

Configuration Examples

OpenAI Configuration

{
  "api_key": "sk-proj-...",
  "organization": "org-...",
  "model": "gpt-4o",
  "max_tokens": 4096
}

Anthropic Claude Configuration

{
  "api_key": "sk-ant-...",
  "model": "claude-3-sonnet-20240229",
  "max_tokens": 4096
}

Twitch API Configuration

{
  "client_id": "abc123...",
  "client_secret": "def456...",
  "redirect_uri": "https://api.sapientris.com/callback/twitch"
}

Google API Configuration

{
  "api_key": "AIza...",
  "search_engine_id": "custom_search_id",
  "project_id": "my-project-id"
}

Privacy & Security Benefits

User-Level Configuration Advantages:

Privacy: Your API keys never leave your control
Quotas: Use your own API quotas and limits
Billing: Direct billing to your accounts
Customization: Configure services to your preferences
Security: Encrypted storage with user-specific encryption

Security Best Practices

1. Environment Variables

Store API keys in environment variables, never in code:

# .env file
SAPIENTRIS_API_KEY=your_api_key_here
OPENAI_API_KEY=your_openai_key_here

2. Least Privilege

Grant only the minimum permissions required:

{
  "permissions": [
    "casinos:read",
    "german-market:read"
  ]
}

3. Key Rotation Schedule

Development: Rotate every 6 months
Production: Rotate every 3 months
High-security: Rotate monthly

4. Usage Monitoring

Monitor API key usage for anomalies:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.sapientris.com/v1/user/api-keys/{key_id}/usage

5. IP Restrictions (Enterprise)

Restrict API key usage to specific IP addresses:

{
  "ip_whitelist": [
    "192.168.1.100",
    "10.0.0.0/8"
  ]
}

Rate Limits & Usage

SAPIENTRIS API Rate Limits

| Key Type | Requests/Hour | Requests/Day | Burst Limit | |----------|---------------|--------------|-------------| | Personal Free | 1,000 | 10,000 | 100 | | Personal Premium | 10,000 | 100,000 | 500 | | Enterprise | Custom | Custom | Custom |

Third-Party API Usage

Third-party API usage depends on your own API quotas and limits:

OpenAI: Uses your OpenAI quota and billing
Anthropic: Uses your Anthropic quota and billing
Twitch: Uses your Twitch API rate limits
Google: Uses your Google API quotas

Benefits:

No additional costs from SAPIENTRIS
Full control over your usage and spending
Direct access to latest API features
Personal quota isolation

Troubleshooting

Common Issues

401 Unauthorized

Check API key is correct and not revoked
Verify key hasn't expired
Ensure proper Authorization header format

403 Forbidden

Check key has required permissions
Verify resource access rights
Contact support for permission updates

429 Rate Limited

Implement exponential backoff
Upgrade to higher tier if needed
Distribute requests across multiple keys

Support

For API key issues, contact support with:

Key ID (not the actual key)
Error messages and timestamps
Expected vs actual behavior