Skip to main content
Engra

API key configuration

Create platform API keys (inf_ prefix) in the console for Agent Memory REST/MCP and AI Gateway proxying. This guide covers scopes, bindings, and request headers; see each product API doc for endpoint details.

Platform keys vs upstream keys

Engra API keys are team-scoped credentials generated in the console (only a hash is stored). The full secret is shown once at creation. They are not the upstream Gemini/OpenAI keys configured on a Gateway — those are used server-side when the Gateway forwards requests; clients only send the platform key.

Local dev may use PLATFORM_API_KEYS in .env as a placeholder. Production must use dashboard inf_ keys; env placeholders are rejected.

Create in the console

  1. Sign in → sidebar API keys (/dashboard/keys)
  2. Enter a descriptive name (e.g. “Cursor MCP”, “CI Gateway”)
  3. Select scopes under Gateway / Memory, or use a quick preset below
  4. For Memory: optionally set library access and MCP default library
  5. For Gateway: bind the target Gateway so the key only works on that /g/<public-id>/…
  6. Click Generate and copy the full inf_… string immediately — it cannot be viewed again

→ Console /dashboard/keys

Scopes

Each key may include multiple scopes. The server checks the required scope per API; missing scope returns 403.

ScopeGroupDescription
gateway:generateGatewayGateway text/multimodal generation (Gemini generateContent, OpenAI chat, etc.)
gateway:embedGatewayGateway embedding API
gateway:routesGatewayResolve logical routes (model parameter → route_id)
memory:readMemoryMemory search, GET /atoms, MCP read tools (search / recall / wake-up / list)
memory:writeMemoryWrite atoms, MCP memory_save_atom / memory_correct_atom, POST/PATCH /atoms

Quick presets

PresetScopeUse case
MCP read-onlymemory:readAgents that only retrieve memory (Cursor, Claude Desktop, etc.)
MCP read/writememory:read + memory:writeAgents that should persist durable knowledge during sessions
Gateway defaultgateway:generate + gateway:embed + gateway:routes + memory:readSDK calls to Gateway plus read-only memory access

Gateway binding (optional)

When creating a key you may bind one Gateway in your team. A bound key may only call that Gateway’s public paths; unbound keys may call any Gateway in the same team (the public-id in the URL must still match).

  • Memory MCP / REST: binding is usually unnecessary
  • Gemini SDK with baseUrl /g/<public-id>: binding the matching Gateway is recommended
  • The key’s team must match the Gateway’s team

Library access & MCP default

When memory:* scopes are selected, you can restrict which libraries the key may access and set the default library for MCP.

  • Library access: default is all libraries; restricted mode limits REST and MCP to selected libraries
  • MCP default library: falls back to team MCP Agent policy when unset; when set, MCP uses that library for the key
  • If access is restricted, the MCP default dropdown only lists allowed libraries
  • You can change MCP default and access on existing keys without regenerating

Sending the key

Resolution order: x-goog-api-key → URL ?key= → Authorization: Bearer → X-API-Key.

Memory REST / MCP

  • Authorization: Bearer inf_xxxxxxxx (recommended)
  • X-API-Key: inf_xxxxxxxx

Gateway (Gemini-compatible)

  • x-goog-api-key: inf_xxxxxxxx

Gateway (OpenAI-compatible)

  • Authorization: Bearer inf_xxxxxxxx

MCP Streamable HTTP

  • Authorization: Bearer inf_xxxxxxxx
  • Accept: application/json, text/event-stream (required)
  • Content-Type: application/json

MCP config example

{
  "mcpServers": {
    "engra-memory": {
      "url": "https://mcp.engra.ai/api/v1/memory/mcp",
      "headers": {
        "Authorization": "Bearer inf_xxxxxxxx",
        "Accept": "application/json, text/event-stream",
        "Content-Type": "application/json"
      }
    }
  }
}

Security practices

  • Grant least privilege; read-only agents should not get memory:write
  • Use separate keys per environment or client for easier revocation
  • Never commit keys to git; use env vars or a secret manager
  • Revoke immediately on offboarding or suspected leak
  • key_prefix in the list (first 12 chars) is for identification only — not valid for auth

Common errors

HTTPReason
401 unauthorizedMissing key, invalid key, revoked, or expired
403 forbiddenValid key but missing required scope (e.g. read-only key calling POST /atoms)
403 (Gateway bind)Key bound to Gateway A but request targets Gateway B /g/<public-id>/…
406 (MCP)MCP client missing Accept: application/json, text/event-stream

Who can manage keys

The API keys page is gated by team role:

RoleView keysCreate / revoke
admin✓✓
member✓✓
viewer✓✗

Related