Machine API Contract

OpenAPI JSON composes the canonical management operation catalog with the identity protocol catalog used by the registration controller. It includes the four identity bootstrap endpoints and native Passport device and token endpoints. Operation IDs, parameters, schemas, response contracts and security requirements are taken from those sources, not a second hand-maintained route list in these guides. Public identity requests do not inherit management bearer authentication; OAuth client authentication is described separately.

Discover an operation by its operationId, then use its exact HTTP method and path. Resolve component schema references before constructing a request. Do not invent fields, undocumented write actions or an API route from a similarly named dashboard action. A generic controller handler does not make every possible action a published operation.

Access and Errors#

Protected operations require the declared bearer authentication and scopes. A token does not establish access to every site: site authorization remains enforced server-side. Public documentation returns no keys, account identifiers, analytics or live resource data. The OpenAPI document contains schemas, not results of authenticated calls.

sites.create requires the explicit sites:create permission; sites:write alone only configures existing granted sites. Human consent can select no existing sites for site creation or account-only capabilities. A successfully created site is granted to its creating client, but neither empty selection nor account-only access permits inspecting foreign sites. Site-scoped operations still require the declared scopes, explicit site grants and the owner's membership.

Treat validation failures as a reason to fix the request, not a reason to retry unchanged. Treat denied or missing resources as inaccessible; do not enumerate IDs. Follow documented rate-limit headers and bounded backoff for transient failures. Do not retry writes unless the operation's contract makes that safe. Avoid guessing pagination, filter and date-range semantics; use the supplied schemas and returned pagination metadata.

Management operations use /api/v1/management/actions/{operationId} with the method declared for that operation. Supply site_id only when its input schema calls for it. Writes require Idempotency-Key; bind the same key to the same intended operation and payload. Elevated risks also require explicit human approval through the declared approval contract. An approval_required or interactive_required response is a boundary to honor, not a failure to work around. Credential issuance, account security and provider OAuth interactions must never be inferred from the availability of a generic action handler.

Contract Checks#

Repository tests compare both canonical catalogs with the rendered OpenAPI document, check operation ID uniqueness, resolve local schema references, require matching declared path parameters, and compare published operations with registered routes. Composition rejects conflicting definitions instead of silently overwriting them. Documentation link tests use the local Laravel kernel, never production HTTP. If a private machine operation is not in the live catalog, it is not advertised here as implemented.

Machine discovery reads complete Markdown sources from the current documentation catalog. It does not use truncated search-index text, render React, require Inertia SSR, write generated files or introspect accounts and token stores.