Docs/API Reference/Authentication

Authentication

Learn how to authenticate with the Ilara API using API keys, understand key types, and implement secure authentication in your applications.

5 min read

Overview

Ilara uses API keys to authenticate requests. Include your API key in the X-API-Key header with every request.

Authentication Header
bash
curl -X GET class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/players/players" \
  -H class="code-string">"X-API-Key: pk_live_your_api_key"

API Key Types

TypePrefixUsageSecurity Level
Public Key (Live)pk_live_Production game clientsSafe to embed in apps
Public Key (Test)pk_test_Development and stagingSafe to embed in dev builds
Secret Key (Live)sk_live_Production backend serversNever expose publicly
Secret Key (Test)sk_test_Development backendNever expose publicly
Secret Key Security
Secret keys (sk_*) have full access to your project data. Never include them in game clients, mobile apps, or frontend code. Use them only on your backend servers.

Key Permissions

Public Keys (pk_*)

Public keys can:

  • Identify players
  • Track events
  • Evaluate feature flags
  • Check segment membership
  • Record sessions and purchases

Public keys cannot:

  • List all players
  • Create or modify flags
  • Create or modify segments
  • Access admin endpoints
  • Delete data

Secret Keys (sk_*)

Secret keys have full access including:

  • All public key capabilities
  • List and query all players
  • Create, update, delete flags
  • Create, update, delete segments
  • Manage campaigns and interventions
  • Access analytics APIs
  • Configure integrations

Generating Keys

  1. Log in to your Ilara dashboard
  2. Go to Settings → API Keys
  3. Click "Generate New Key"
  4. Select key type (Public or Secret)
  5. Copy the key immediately - secret keys are only shown once
Key Management
Generate separate keys for different environments (development, staging, production) and rotate keys periodically.

Environments

Test and Live environments are completely isolated:

EnvironmentKey PrefixDataUse For
Test*_test_Separate sandboxDevelopment, QA, staging
Live*_live_Production dataReleased games
Environment Switching
csharp
#if UNITY_EDITOR || DEVELOPMENT_BUILD
    const string API_KEY = class="code-string">"pk_test_development_key";
#else
    const string API_KEY = class="code-string">"pk_live_production_key";
#endif

Authentication Errors

StatusCodeDescription
401UNAUTHORIZEDMissing or invalid API key
401KEY_DISABLEDAPI key has been disabled
401KEY_EXPIREDAPI key has expired
403FORBIDDENKey lacks required permissions
Error Response
json
{
  class="code-string">"success": false,
  class="code-string">"error": {
    class="code-string">"code": class="code-string">"UNAUTHORIZED",
    class="code-string">"message": class="code-string">"Invalid API key provided"
  }
}

Best Practices

  • Environment variables: Store keys in environment variables, not code
  • Rotate regularly: Rotate keys periodically (every 90 days recommended)
  • Separate keys: Use different keys for different services/environments
  • Monitor usage: Watch for unusual API usage patterns
  • Revoke compromised: Immediately revoke keys if exposed

Next Steps

Previous
Webhooks
Next
Events API