Developer Console: API Keys and the External Read API

The Developer Console is the firm’s programmatic surface: named API keys that let a third-party system read the firm’s study record, and a small read-only external API under /api/v1/external/ that those keys call. It is built for integration, not for general access — the surface is deliberately narrow.

The console

Plan feature: This capability requires the api_access plan feature (see Plan Features).

Available to Partner, Firm Admin and Superadmin roles (and only where the firm’s plan holds the feature), the console manages the firm’s keys. Without the feature the entry point is absent from the sidebar and direct navigation is redirected — the server-side feature check is the boundary, not the menu.

• Create — a name produces a new key. Scope is not a choice: every key is read-only, and there is no write scope to ask for. The raw key is returned in the create response and never again (“store it securely, it will not be shown again”) — the server keeps only its SHA-256 digest, never the value. Keys are minted with a fixed tpip_live_ prefix, so a stray string found in a log or a repository is recognisable as a Quartyl credential.
• List — keys newest first, each with its name, the leading characters of the key (never the full value), scope, status (Active or Revoked), creation time, and last-used and revoked timestamps. Last-used is the hygiene signal: a key that has never been used is a key to delete.
• Revoke — an immediate, permanent stop: a revoked key no longer authenticates on the next request. The row stays listed as Revoked for audit and revocation is logged to the access ledger with the actor, the IP and the user agent.

There is no edit-in-place and no expiry: a key’s name and scope are fixed at creation and it lives until it is revoked. Rotation is therefore create-then- revoke.

The external read API

Authentication is the X-Api-Key header. The endpoints a key can call are read-only and study-scoped — these two GETs are the entire surface:

Endpoint	Returns
GET /api/v1/external/studies	The credential’s studies, newest first (50 by default, limit up to 100)
GET /api/v1/external/studies/{id}	A single study summary, when visible to the credential

The summary is the study’s engagement record — name and description, entity, financial year, jurisdiction, margin type and PLI, function and nature of business, workflow status, the arm’s length conclusion, accepted/rejected counts and total entities, whether analysis is ready, and the timestamps — not the raw comparable dataset, uploaded files or analysis rows. There is no mutation endpoint under /external/. Three behaviors make the surface safe to leave running:

• Entitlement is re-checked on every request. A tenant that loses the feature has its existing keys refused immediately — no lingering grace for a key created while the feature was licensed.
• Every machine call is logged. Each call stamps the key’s last-used time and writes an access-ledger entry (key, actor, IP, agent), so machine traffic is inspectable in the access and security logs like any other firm activity.
• Scope is the credential’s boundary. A firm key sees its tenant’s undeleted studies and nothing else; a study outside the boundary is a 404, not an empty result.

What the surface does not have: request signing beyond the key itself, per-key throttling, or IP restrictions. There is no rate limit on the external endpoints, so an integration that misbehaves is contained by revoking its key, and anything tighter belongs in your own gateway. Keys also carry no expiry — an offboarding checklist must include them.

Platform keys (superadmin, owner-scoped)

A tenant-less platform account (Superadmin) may also create keys — and the scoping follows the platform’s owner rule: the key sees only the studies its owner created (created_by), never another firm’s studies, and a key is only listable and revocable by its owner. A platform key is an owner’s integration, not a platform-wide back door.

Key hygiene

The console makes the obvious practices possible; the practices still belong to the firm:

• Rotate, don’t reuse. Create the replacement, verify the integration, revoke the old key — revocation is instant, so the cutover window is yours to control.
• Least privilege. One key per integration, named for it — “ERP export” beats “key 7” when the access log says a key was used from an unexpected IP.
• Never commit a key. The raw value is shown once for a reason; a key in source control is a leaked credential. Revoke and rotate when in doubt.
• Revoke on offboarding. A person who leaves with a live integration key is an open door; revocation is immediate and logged.

The broader firm policy surface — the MFA mandate and what is and is not enforceable per firm today — is in Security Settings.

FAQ

Can an external key write to a study? No — the external surface is read-only and every key is read-scoped at creation.

What happens to our keys if we lose the feature? They stop working on the next request — entitlement is checked per call, and re-adding the feature restores them.

Why does a study we know exists return 404 on the external API? The key’s scope does not include it — a firm key is bound to its tenant, a platform key to its owner’s studies — or the study has been deleted. Outside the boundary, a study is simply not there.