Authentication

Estuary uses API keys for all SDK and REST API authentication. This page covers how to obtain keys, how the Socket.IO handshake works, and how to authenticate REST requests.

API Keys

What They Are

An API key is a secret token that identifies your account and grants access to the Estuary platform. Each key is scoped to a single account and can be used across all characters you own.

API keys follow the format est_ followed by a random string:

est_a1b2c3d4e5f6g7h8i9j0...

Generating Keys

1. Sign in to the Estuary Dashboard
2. Navigate to Settings > API Keys
3. Click Generate New Key
4. Copy the key immediately -- it is only shown once

warning

Keep your API key secret. Do not commit it to source control or expose it in client-side code that end users can inspect. For native builds, load the key at runtime from a secure source rather than bundling it with the application.

---

Socket.IO Connection Handshake

SDKs authenticate when connecting to the Socket.IO /sdk namespace. The authentication payload is sent as part of the namespace connection message.

Connection Flow

Client                              Server
  │                                   │
  │── WebSocket connect ────────────>│  (Engine.IO handshake)
  │<── 0 {sid, upgrades} ───────────│
  │                                   │
  │── 40/sdk,{auth payload} ────────>│  (Socket.IO namespace connect)
  │                                   │
  │     ┌─ success ─┐                │
  │<── session_info ─────────────────│
  │                                   │
  │     ┌─ failure ──┐               │
  │<── auth_error ───────────────────│

Auth Payload

The authentication payload is a JSON object with these fields:

Field	Type	Required	Description
api_key	string	Yes	Your Estuary API key
character_id	string	Yes	UUID of the character to connect to
player_id	string	Yes	Unique identifier for the end user
audio_sample_rate	number	Yes	Sample rate for TTS audio (e.g., 48000 for Unity, 24000 for web)

Example:

{
  "api_key": "est_a1b2c3d4...",
  "character_id": "550e8400-e29b-41d4-a716-446655440000",
  "player_id": "player_abc123",
  "audio_sample_rate": 48000
}

Session Info Response

On successful authentication, the server emits a session_info event:

{
  "session_id": "sid_abc123",
  "conversation_id": "conv_def456",
  "character_id": "550e8400-e29b-41d4-a716-446655440000",
  "player_id": "player_abc123"
}

Field	Description
session_id	Unique identifier for this connection session
conversation_id	Persistent conversation ID -- the same player+character pair always resumes the same conversation
character_id	The character this session is connected to
player_id	The player ID provided during authentication

Auth Errors

If authentication fails, the server emits an auth_error event:

{
  "error": "Invalid API key"
}

Common error causes:

Error	Cause
Invalid API key	The API key is incorrect or revoked
Character not found	The character_id does not exist or does not belong to this account
Missing required field	A required auth field was not provided

After an auth_error, the connection is closed by the server. SDKs should not retry with the same credentials.

---

REST API Authentication

REST API requests authenticate using the X-API-Key header:

GET /api/characters HTTP/1.1
Host: api.estuary-ai.com
X-API-Key: est_a1b2c3d4...

All REST endpoints require this header. Requests without a valid key receive a 401 Unauthorized response.

---

Player IDs

The player_id is a string you choose to uniquely identify each end user of your application. It serves two purposes:

1. Conversation persistence -- The same player_id + character_id pair always resumes the same conversation with full memory context.
2. Memory isolation -- Each player has their own memory graph. The character remembers different things about different players.

Player IDs can be any string up to 128 characters. Common strategies:

• Use your own user ID system (database ID, Firebase UID, etc.)
• Generate a random UUID and persist it locally (PlayerPrefs in Unity, localStorage in web)
• Use a device identifier for anonymous users

tip

If you change a player's ID, the character will treat them as a new person with no conversation history. Use consistent IDs to maintain memory continuity.

---

Next Steps

• Conversation Protocol -- The full event reference for text and voice
• Memory System -- How player memory works across sessions