# Capability publication and authorization

The public integration contract is read-only catalogue discovery. Its access
boundary is the project's publication setting, rather than a caller token.

## Credentials and transport

GET `/v1/capabilities.json?project_id=PROJECT_UUID` requires no credential when
the project is active and publicly discoverable. Use HTTPS. Send only
`project_id` and optional `revision` as query fields; never put an access token,
refresh token, client secret or private key in a URL. This request does not use
an organization workspace, Bearer authentication or DPoP proof.

A token does not override a project's private or archived publication state.
Use the [Capability application](https://capability.service.m7.org/) with an
authorized operator account to arrange publication and obtain the intended
catalogue project ID.

## Project and workspace boundary

Public discovery is off when a project is created. Its Owner can enable it
explicitly. A missing, private or archived project returns HTTP 404, including
when a historical revision was requested. Public visibility exposes catalogue
definitions and metadata, not management memberships or credentials.

The management application uses M7 sign-in and current receiving-service
admission. Personal and organization workspaces retain separate project access.
Organization management uses current direct Management Owner/Admin authority;
the actual authenticated actor remains attributed separately. Each catalogue
project has its own Management group: Owners control publication and lifecycle,
Admins edit its catalogue, and Members read its catalogue through the tools.
Admission to the service alone does not grant access to another project.

If you need to sign in to the management application, use its M7 sign-in flow.
[M7 SSO](https://m7.org/docs/api/sso.user.m7.org/) owns token issuance, expiration,
refresh and revocation. Keep confidential-client credentials server-side and
follow the credential lifecycle of the sign-in client. Public discovery itself
has no token acquisition or refresh step.

## Definitions and grants

A public capability or preset is a definition. Resolving it does not
authenticate a principal, enroll it in a consumer, change its membership role
or authorize access to a resource. Your receiving service must establish the
caller and apply its own current resource boundaries before using an allowed
primitive for an operation.

Keep a catalogue project's ID distinct from consumer resource IDs, organization
IDs and authenticated principal IDs. A frontend and API can share a catalogue
project for the same logical service; that does not merge their credential
audiences or resource access.

## Failures

HTTP 404 means the catalogue is not publicly available or the selected revision
does not exist; check publication and the project/revision mapping with its
Owner. HTTP 400 means malformed query input. HTTP 503 means unavailable or
invalid catalogue storage; retry with backoff and fail closed. Inspect
`status: 0` and `data.code` in the error envelope.

See [discovery and resolution](https://m7.org/docs/api/api.capability.service.m7.org/discovery.md) for the exact request and document
contract.