Authentication and conventions

Authentication#

Every request carries the bearer token of the shared Beyond authority, the same identity Workspace uses:

GET /v1/session HTTP/1.1
Authorization: Bearer <token>

The CDN keeps no accounts and no memberships. An organization is a Workspace team, and the CDN stores only opaque organization and user identifiers. Guest tokens of private applications are never accepted by this API.

session.read answers the signed-in user, its organizations, roles, CDN capabilities and a plan summary. organization.read answers the context of one organization of the caller. When the authority cannot be reached the answer is 502 UPSTREAM_UNAVAILABLE, never a refusal or an approval.

Roles and capabilities#

Roles come from the authority: owner, admin, developer, viewer and none. The CDN owns a table of capabilities over those roles, and each operation names the capability it requires.

The role none has no capability and hides the organization's resources.

Two operations require a capability that depends on the environment they act on: promotion and rollback need release.prepare for testing and release.promote for production. The contract states this in a machine-readable form, x-beyond-capability-by, next to x-beyond-capability.

Refusals follow one rule. A resource the caller cannot see answers 404 NOT_FOUND, so its existence is not disclosed. A visible resource the role cannot act on answers 403 FORBIDDEN.

Operations under /v1/platform belong to the platform backoffice. They require a platform operator capability that no organization role implies, and they answer NOT_FOUND to everyone else. They are not documented here.

Registry providers#

An organization can resolve packages from registries other than the public one, for example a private registry for one npm scope. The settings belong to the organization and are used by the registrations that run afterwards. Pinned graphs and existing releases never change.

Version 1 reads npm-compatible registries that are reachable over the Internet. A registry reachable only through a private network or a VPN is outside version 1: the workers reach public Internet addresses only, and a registry address that cannot be one is refused when it is saved.

{provider} is default, for every package without a scope setting, or an npm scope such as @acme.

{ "registry": "https://<registry host>", "token": "<registry token>" }

Removing a provider makes the packages of that scope resolve from the default registry again. Removing an absent provider answers the same.

Visibility belongs to the package#

Whether a package is public is decided for each package, not by the credential it was read with:

• A package read without a credential is public.
• A package read with a credential is public only when the same registry, asked anonymously, answers the same version with the same integrity and the same archive, and the archive itself answers anonymously. Any doubt keeps it private: a registry answers "not found" and "not allowed" alike to an anonymous client.
• A Git repository or an archive URL read with a credential is private.

A public package produces public outputs, even when your token was used to read it, and it is downloaded without the token. A private package stays in your organization, and so does every output that reads it, including a public package's module that imports it. A private application does not make its public dependencies private. Removing a token does not make bytes that were already retained public. See Preparation and inventory.

Retries and concurrent changes#

Each mutation states how it tolerates a retry:

An Idempotency-Key matches ^[A-Za-z0-9_.:-]{8,128}$, is chosen by the client, is unique per intended mutation and is scoped to the caller's organization. If a request times out, send it again with the same key: never generate a new key for a retry.

Pagination#

List operations take limit (1 to 200, default 50) and after. A page answers items and, when there is more, next. Send next back as after. Cursors are opaque.

Identifiers#

Errors#

Failures use one envelope, shared in shape with the delivery contract. details replaces diagnostics:

{ "error": { "code": "CONFLICT_VERSION", "message": "…", "details": { "current": 7 } } }

Codes are stable and never translated. The reasons a job can fail are a separate vocabulary that travels inside documents and events; see Jobs.

No GET starts work#

No GET of this API, and no GET of published delivery, starts, resumes or schedules work. Only the explicit POST operations create jobs. Reading a job, a release or an inventory as often as you like is safe.