Studio API and API keys

Overview

• The API lives under /api/b2b/v1 and speaks JSON.
• There is no anonymous access. The machine-readable API reference (an OpenAPI document) and the contract endpoints that list scopes, rate limits, error codes and deprecations are available to signed-in members and to API keys, not to the public.
• List endpoints are paged with cursors.
• Live streams are opened with a short-lived stream ticket, which is single-use and valid for 60 seconds.

API keys

Owners and Admins create API keys in the studio app. Each key has:

• a level, which sets the most it can ever do;
• scopes, which narrow the level to what your tooling needs;
• optionally, a restriction to specific groups, hosts or servers;
• optionally, an IP allow-list, so the key only works from your own addresses;
• optionally, its own rate limit, from 1 to 600 requests a minute (60 by default);
• an expiry date.

The key's secret is shown once, when it is created. A key can never do more than the member who owns it can do today: if that person's role is reduced, their keys are reduced with it.

Rotation and revocation

Rotating a key issues a successor and keeps the old key working for a grace period you choose (24 hours by default, up to 168), so you can roll the new secret out without downtime. Any key can be revoked at any time.

Keys are created, edited and rotated only from a signed-in member session. A key can never create another key.

What keys cannot reach

Some things are for people only, whatever a key's scopes: single sign-on and SCIM settings, accepting legal documents, and opening Remote Desktop or terminal sessions. Keys are not subject to the multi-factor authentication requirement, which is another reason to give each key only the scopes it needs and an IP allow-list.

Key levels

A key's scopes must fit inside its level. The levels, from most to least powerful:

The Monitoring only level is meant for dashboards and holds exactly monitoring:read and alerts:read.

Scopes

These scopes are refused outright and can never be issued: keys:write, builds:read, builds:write, metrics:read and legal:accept.

Rate limits

Requests are counted over a rolling minute in several buckets at once, and a request must fit in all of them:

In the weighted buckets, the limit is multiplied by the weight of the route being called, so light calls can be made more often than heavy ones:

Separately, no single key or member can make more than 600 requests a minute, however the calls are weighted.

A refused request answers 429 with a Retry-After header, and responses carry X-RateLimit-* headers describing the bucket.

Errors

Errors are returned as JSON problem documents in the RFC 9457 shape (type, title, status, detail), with a stable machine-readable code and a requestId. Quote the requestId in a support ticket and we can find the exact request.

An error code never changes meaning once it has shipped; a condition whose meaning changes gets a new code.

Idempotency

Send an Idempotency-Key header (up to 255 characters) on a POST and a retry of the same request is answered from the first result instead of being carried out twice. Keys are remembered for 24 hours.

• A replayed answer carries Idempotency-Replayed: true.
• The same key with a different body is refused with 422 (IDEMPOTENCY_KEY_REUSED).
• The same key while the first request is still running is refused with 409 (IDEMPOTENCY_IN_PROGRESS).

Versioning

• The version is the path prefix. Within v1, new response fields, optional request fields, enum values, routes and scopes can be added at any time, so clients must ignore fields they do not recognise.
• A breaking change is released under a new prefix, served alongside v1 rather than replacing it.
• A route that is going away keeps working and answers with Deprecation, Sunset and Link headers, with at least 365 days between deprecation and sunset. A contract endpoint lists everything currently deprecated.