Skip to main content

​
Client API Auth, Errors, and Limits

​
Authentication

Send your OMNI API key in bearer format: 
Authorization: Bearer omni_live_...
Supported key prefixes:
  • omni_live_...
  • omni_test_...

​
Scopes (restricted keys)

OMNI supports restricted API keys via scopes. Behavior:
  • Keys with no scopes are treated as unrestricted.
  • Keys with scopes must include the required scopes for the endpoint/tool.
If a scoped key is missing permissions, OMNI returns:
  • HTTP 403
  • error.type = permission_error
  • error.code = insufficient_scope
  • Omni-Required-Scopes header (space-delimited scopes) to help you debug
See /sources/client-api-keys for key creation and scope updates.

​
Scope catalog (v1)

ScopeWhat it allowsRequired for
fred.readRead access to FRED REST endpoints and FRED tools.GET /v1/fred/*, fred.* tool calls
mcp.tools.readRead the tool catalog.GET /v1/mcp/tools, hosted tools/list
mcp.invokeInvoke tools.POST /v1/mcp/invoke, hosted tools/call
Notes:
  • GET /v1/openapi.json requires authentication, but does not require any specific scope.

​
Request tracing

Optional inbound request ID: 
X-Request-Id: req_123
The API echoes X-Request-Id in responses.

​
Version pinning

Optional version header: 
Omni-Version: 2026-02-17
The API echoes Omni-Version in responses.

​
Idempotency

POST endpoints require: 
Idempotency-Key: <unique-key-per-operation>
Repeated requests with the same key and payload replay the stored response. Idempotency applies to:
  • POST /v1/mcp/invoke
  • Hosted MCP tools/call requests sent to POST /mcp

​
Error envelope

All errors use: 
{
  "error": {
    "type": "invalid_request | auth_error | permission_error | rate_limit_error | api_error",
    "code": "machine_readable_code",
    "message": "Human-readable error",
    "request_id": "req_xxx"
  }
}

​
Rate limiting

Per-key limits apply:
  • burst window limits
  • sustained per-minute limits
Rate-limited responses:
  • 429 Too Many Requests
  • Retry-After header
  • X-RateLimit-Limit-Burst header
  • X-RateLimit-Limit-Minute header