Skip to content

Authentication

The Go SDK supports three authentication modes, selected via sdk.Config.Auth.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",
},
})

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.

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:

  1. Call auth.DiscoverOIDC(serverURL) to discover the OIDC configuration
  2. Initiate the device flow and print the verification URL and user code to stdout
  3. Poll for a token until the user completes authorization
  4. Store the credentials at CredsPath for future use
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
}

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.

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.