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

Type	Prefix	Usage	Security Level
Public Key (Live)	`pk_live_`	Production game clients	Safe to embed in apps
Public Key (Test)	`pk_test_`	Development and staging	Safe to embed in dev builds
Secret Key (Live)	`sk_live_`	Production backend servers	Never expose publicly
Secret Key (Test)	`sk_test_`	Development backend	Never 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

Log in to your Ilara dashboard
Go to Settings → API Keys
Click "Generate New Key"
Select key type (Public or Secret)
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:

Environment	Key Prefix	Data	Use For
Test	`*_test_`	Separate sandbox	Development, QA, staging
Live	`*_live_`	Production data	Released 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

Status	Code	Description
401	`UNAUTHORIZED`	Missing or invalid API key
401	`KEY_DISABLED`	API key has been disabled
401	`KEY_EXPIRED`	API key has expired
403	`FORBIDDEN`	Key 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

Events API — Track player events
Players API — Manage player profiles
Feature Flags API — Evaluate flags

Webhooks

Events API