Authentication

The Go SDK supports three authentication modes, selected via sdk.Config.Auth.Mode.

API Key Mode

Used for standalone Emergent 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",
    },
})

Auto-detection of API tokens

When Mode: "apikey" is used, the SDK automatically checks whether the key starts with emt_. If it does, the key is treated as an API token (Bearer auth) rather than a standalone API key (X-API-Key). This means you can use Mode: "apikey" for both key types and let auth.IsAPIToken handle the routing.

API Token Mode

Project-scoped tokens with the emt_* prefix. Sets the Authorization: Bearer <token> header.

client, err := sdk.New(sdk.Config{
    ServerURL: "https://api.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

For full Emergent 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://api.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

OAuth not available via sdk.New

Mode: "oauth" in sdk.New returns an error; OAuth always requires NewWithDeviceFlow.

Config Reference

type Config struct {
    ServerURL  string       // Required: base URL of the Emergent 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

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)

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_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_API_KEY	api_key	API key or emt_* token
MEMORY_PROJECT_TOKEN	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_TOKEN is set it takes precedence over MEMORY_API_KEY as the credential.