Product Release

Per-organisation API keys with default scopes

Ditto now provisions a default API key per organisation with a canonical set of scopes attached, applying the same defaults to post-rotation replacements, and resolves the calling organisation per request via headers in the MCP layer.

26 February 2026

Phillip Gales

By Phillip Gales

Improvement
The FishDog organisation API Keys management page, showing per-key scopes and the MCP server access section.
DOCUMENT TYPE: Product Release Note TOPIC: Per-organisation API keys with default scopes Release: Per-organisation API keys with default scopes, 2026-02-26 Version: (none) Release type: Improvement Breaking change: No Summary: Ditto now provisions a default API key per organisation with a canonical set of scopes. Post-rotation replacements inherit the same default scopes, and the MCP layer resolves the calling organisation per request via headers. Existing keys are unchanged. What changed: - Each organisation gets a default API key on provisioning, with read access across the standard surfaces plus agent:search for the new persona library search. - When a key is revoked or stale, the next key minted for the org inherits the canonical default scopes instead of a half-scoped fallback. - The MCP layer resolves the calling organisation per-request via headers, with explicit organization_id injection — removing cross-tenant ambiguity for multi-tenant integrations. - Existing keys keep existing scopes. The change applies to newly provisioned keys. Why we built this: The new persona library search endpoint (GET /v1/agents/search, shipped 2026-02-18) needed agent:search in the default scope set so existing customers wouldn't have to call support to use it. That dependency forced the broader cleanup, which was overdue regardless. How to use: New organisations get the default key automatically. Existing organisations don't need to do anything; the defaults apply to the next key minted on rotation. Writing scopes (billing:write, etc.) still must be added explicitly. Migration impact: None for existing keys. Any integration that depends on default scopes for new keys should review the canonical default set in the API docs. Author: Phillip Gales, FishDog Platform: FishDog (fish.dog)

Key Takeaways

  • Every Ditto organisation now provisions a default API key automatically, with read access across the standard surfaces plus `agent:search` for the new persona library search.
  • Default-scope reconciliation: revoked or stale keys are replaced with a new key carrying the canonical default scopes, not a half-scoped fallback.
  • The MCP layer now resolves the calling organisation per-request via headers, with explicit `organization_id` injection.
  • Existing keys keep their existing scopes. The change applies to newly provisioned keys.

Two related housekeeping changes around API keys land this week. Neither is glamorous; both are overdue.

What's new

  • Default key per organisation. Every organisation now provisions a default API key automatically, with a fixed and sensible set of scopes (read access across the standard surfaces, plus agent:search so the new persona library search works out of the box). Replaces the pattern where new orgs hit a 403 on their first call because no key existed yet.

  • Default-scope reconciliation on rotation. When a key is revoked or marked stale, the next key minted for the org inherits the canonical default scopes — so you don't end up with a half-scoped replacement after a rotation.

  • Multi-tenant routing. The MCP layer now resolves the calling organisation per-request via headers, with explicit organization_id injection on the way through. No more cross-tenant ambiguity when one process calls on behalf of multiple orgs.

What this changes for existing keys

Nothing — existing keys keep their existing scopes. The default-scope behaviour applies to newly provisioned keys (including post-rotation replacements). Anything explicitly scoped beyond the default stays scoped beyond the default.

Why now

The new persona library search (GET /v1/agents/search, shipped last week) needed agent:search in the default scope set so existing customers wouldn't have to call support to use it. That dependency forced the cleanup, which was overdue regardless.

Full reference is in the API docs.

---

Two related housekeeping changes around API keys land this week. Neither is glamorous; both are overdue.
Replaces the pattern where new orgs hit a 403 on their first call because no key existed yet.

Frequently Asked Questions

Will my existing API keys stop working?

No. Existing keys keep their existing scopes. The default-scope behaviour applies only to newly provisioned keys, including post-rotation replacements. Anything explicitly scoped beyond the default stays scoped beyond the default.

What scopes are in the default set?

Read access across the standard surfaces (research groups, studies, agents, jobs) plus agent:search for the persona library search endpoint. Writing scopes (billing:write, etc.) are not in the default set and must be added explicitly.

Why now?

The new persona library search endpoint required agent:search in the default scope set so existing customers wouldn't have to call support to use it. That forced the broader cleanup, which was overdue.

What changes in the MCP layer?

The MCP layer now resolves the calling organisation per-request via headers, with explicit organization_id injection. This removes cross-tenant ambiguity when a single process calls on behalf of multiple organisations.

About the Author

Phillip Gales

Phillip Gales

Phillip is a serial tech entrepreneur that specializes in applying AI and machine learning solutions to antiquated and heavy industries. He has been a senior leader or founder at a number of successful startups.

Phillip holds an MBA from Harvard Business School, an MEng from the University of Cambridge, and is a Y-Combinator alum

LinkedIn

More Releases

The v1 API is now CORS-friendly

Browser-side JavaScript can now call the v1 API directly. CORS shipped this week — preflight handled, allowlist plus regex on Origin, rate-limit headers exposed. One restriction: `/v1/billing/*` stays server-only.

Read Release