Authentication
The Go SDK supports three authentication modes, selected via sdk.Config.Auth.Mode.
API Key Mode
Section titled “API Key Mode”Used for standalone Memory deployments. Sets the X-API-Key header on every request.
client, err := sdk.New(sdk.Config{ ServerURL: "http://localhost:9090", Auth: sdk.AuthConfig{ Mode: "apikey", APIKey: "your-standalone-api-key", },})API Token Mode
Section titled “API Token Mode”Project-scoped tokens with the emt_* prefix. Sets the Authorization: Bearer <token> header.
client, err := sdk.New(sdk.Config{ ServerURL: "https://memory.emergent-company.ai", Auth: sdk.AuthConfig{ Mode: "apitoken", APIKey: "emt_abc123...", // always an emt_* token in this mode },})This is equivalent to using Mode: "apikey" with an emt_* prefixed key, but makes the
intent explicit.
OAuth Device Flow
Section titled “OAuth Device Flow”For full Memory deployments with OIDC/OAuth. Initiates an interactive device-code flow, then polls for a token and stores credentials to disk.
client, err := sdk.NewWithDeviceFlow(sdk.Config{ ServerURL: "https://memory.emergent-company.ai", Auth: sdk.AuthConfig{ Mode: "oauth", ClientID: "emergent-sdk", CredsPath: "~/.emergent/credentials.json", },})NewWithDeviceFlow will:
- Call
auth.DiscoverOIDC(serverURL)to discover the OIDC configuration - Initiate the device flow and print the verification URL and user code to stdout
- Poll for a token until the user completes authorization
- Store the credentials at
CredsPathfor future use
Config Reference
Section titled “Config Reference”type Config struct { ServerURL string // Required: base URL of the Memory server Auth AuthConfig OrgID string // Optional: default organization ID ProjectID string // Optional: default project ID HTTPClient *http.Client // Optional: custom HTTP client (default: 30s timeout)}
type AuthConfig struct { Mode string // "apikey", "apitoken", or "oauth" APIKey string // Key/token value for apikey or apitoken mode CredsPath string // File path for OAuth credential storage ClientID string // OAuth client ID}auth Package
Section titled “auth Package”For advanced use, the auth package is importable directly:
import "github.com/emergent-company/emergent.memory/apps/server/pkg/sdk/auth"See the auth reference for the full Provider interface, credential
helpers, and OIDC discovery.
Auto-discovery (NewFromEnv)
Section titled “Auto-discovery (NewFromEnv)”sdk.NewFromEnv() discovers configuration automatically — no arguments needed. This is the recommended pattern when running inside agent sandboxes or CI environments.
client, err := sdk.NewFromEnv()Resolution order (highest priority wins):
| Source | Example |
|---|---|
MEMORY_* env vars |
MEMORY_SERVER_URL=http://... |
.env.local (walked up from cwd) |
MEMORY_ACCOUNT_API_KEY=emt_abc123 |
.env (walked up from cwd) |
MEMORY_PROJECT_ID=proj_1 |
~/.memory/config.yaml |
api_key: emt_abc123 |
Recognised variables / YAML keys:
| Env var | YAML key | Purpose |
|---|---|---|
MEMORY_SERVER_URL (or MEMORY_API_URL) |
server_url |
Server URL |
MEMORY_ACCOUNT_API_KEY |
api_key |
API key or emt_* token |
MEMORY_PROJECT_API_KEY |
project_token |
Project-scoped token (overrides api_key) |
MEMORY_ORG_ID |
org_id |
Default organisation ID |
MEMORY_PROJECT_ID |
project_id |
Default project ID |
If MEMORY_PROJECT_API_KEY is set it takes precedence over MEMORY_ACCOUNT_API_KEY as the credential.