Skip to content

Add first-class X-Org-Id support on the SDK Client builder #82

@chaliy

Description

@chaliy

Summary

Add first-class support for the X-Org-Id header on everruns-sdk's
Client. Today, API-key principals with access to multiple
organizations hit:

Multiple organizations available. Specify the target organization via
the X-Org-Id header.

…and there is no typed way to set it — you have to monkey-patch the
registry source or rely on an environment variable that isn't part of
the public API.

Context

Found while running an Everruns agent
(everruns/a11y-nanny) against
dev.everruns.com with an API key that had access to more than one org.

The workaround I used in-tree was to patch
everruns-sdk-0.1.8/src/client.rs::headers() to read EVERRUNS_ORG_ID
from the environment and inject it as X-Org-Id:

if let Ok(org) = std::env::var("EVERRUNS_ORG_ID") {
    if let Ok(v) = HeaderValue::from_str(&org) {
        headers.insert("X-Org-Id", v);
    }
}

That works but:

  • It's not discoverable from the type signature.
  • Env-var-only means callers in containers / hosted runtimes have to
    remember to set it.
  • It silently drops invalid header values.

Proposal

Add a typed builder option on Client::builder() (or whichever builder
the SDK exposes) plus a documented precedence:

  1. Explicit builder.org_id(...) / Everruns::builder().org_id(...).
  2. EVERRUNS_ORG_ID env var.
  3. Omitted (single-org accounts don't need it).

Behaviour:

  • When set, every request carries X-Org-Id: <value>.
  • Invalid header value returns a typed error at build time, not
    silently swallowed.
  • from_env() picks up EVERRUNS_ORG_ID automatically, same as
    EVERRUNS_API_KEY.

Suggested API

let client = Everruns::builder()
    .api_key(std::env::var("EVERRUNS_API_KEY")?)
    .org_id("org_019...") // new
    .build()?;

// or purely from env
let client = Everruns::from_env()?; // also honours EVERRUNS_ORG_ID

Acceptance criteria

  • Client::builder().org_id(...) compiles and sends
    X-Org-Id on every request.
  • Everruns::from_env() reads EVERRUNS_ORG_ID if present.
  • Precedence: builder value wins over env var.
  • Invalid header value returns a typed build-time error.
  • README Quick Start updated with a multi-org example.
  • Integration test hits a mock server and asserts the header is
    forwarded.

Related

  • CLI-side counterpart (already shipped in the everruns/everruns
    monorepo): commit ee17a05 on branch
    claude/setup-a11y-audit-agent-1Tzkq adds the same env-var
    forwarding to /v1/agents/import. Tracked in Linear as EVE-338.
  • Session that exposed the gap:
    a11y-audit-output/session-019da1bd6745737d92a1266e84475972.jsonl
    on the branch above.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions