Resources HTTP API

This is the reference for the Tenancy Resource HTTP surface. It maps each operation to its OpenAPI schema, ReBAC gate, audit emission, and the closed Problem.code taxonomy. The wire-contract origin is api/openapi/plexsphere-v1.yaml; this doc is a map, not a duplicate contract.

The Resource aggregate spans two origins:

• Adopted (BYO) — the operator registers an already-running workload. Create persists a row and emits a ResourceCreated outbox event; the Broker is NEVER called.
• Provisioned — the operator selects a BlueprintVersion + Cloud Credential and declares the desired workload. Create persists the Resource row, then asks the Broker to mint a Pending ProvisionedResource; the operator polls GET /v1/resources/{id} to observe phase advances.

Operations

Method	Path	Operation ID	ReBAC gate	Audit relation	Outbox event	Body cap
POST	/v1/projects/{project_id}/resources	CreateResource	project#deploy (pre-decode); plus cloudcredential#use (project subject) on provisioned flow	resource.create.{adopted,provisioned}	ResourceCreated (+ ProvisionedResourceRequested on provisioned)	8 KiB
GET	/v1/projects/{project_id}/resources	ListProjectResources	project#observe on the parent Project (top-level) + per-row resource#observe filter	resource.list (granted, with post-filter item_count)	(none)	n/a
GET	/v1/domains/{domain_id}/resources	ListDomainResources	domain#read on the Domain (top-level) + per-row resource#observe filter	resource.list (granted, with post-filter item_count)	(none)	n/a
GET	/v1/resources/{id}	GetResource	resource#observe (BEFORE persistence read)	resource.get	(none)	n/a
DELETE	/v1/resources/{id}	DeleteResource	resource#manage	resource.delete.{adopted,provisioned}	ResourceRemoved (adopted) / ProvisionedResourceDeleting (provisioned, emitted by the broker)	n/a

• body_cap = 8 KiB is enforced before the JSON decoder runs; an over-cap body surfaces as 413 request_body_too_large.
• CreateResource returns:
  • 201 Created with a ResourceResponse body on the adopted flow.
  • 202 Accepted with a Location: /v1/resources/{id} header on the provisioned flow; the body carries the hydrated ResourceResponse with an embedded provisioning.phase = pending.
• ListDomainResources pages the Resources of every Project in the Domain in ascending id order; each item names its Project in project_id. The Domain is not looked up before the domain#read check, so an absent Domain answers the same 403 as one the caller cannot read, and the operation declares no 404. The per-row filter, the provisioning hydrate, the paging and the audit row are the ones ListProjectResources applies.
• ListProjectResources, ListDomainResources and GetResource attach a provisioning sub-object only when the Resource origin is provisioned and the composition root wired a ProvisioningReader port. GetResource reads the single backing row; ListProjectResources hydrates the whole page's provisioned rows through one batch read keyed by resource id, so a page stays at one broker round-trip regardless of its width — never a per-row fan-out. A reader fault on either path degrades to a response without the provisioning sub-object rather than failing the read: a flaky broker must not mask the canonical Resource projection.
• DeleteResource branches on origin:
  • Adopted → remove the Resource row + ResourceRemoved outbox event; responds 204 No Content.
  • Provisioned → record a Broker Deprovision request and respond 202 Accepted; the row stays until the broker finalises.
• limit on both lists must lie in [1, 200] (default 50); a value outside the window answers 400 invalid_limit.
• cursor on both lists is opaque, HMAC-signed by the server through the CursorCodec port; tampered → 400 invalid_cursor; cross-user replay → 403 cursor_binding_mismatch.

Path & query parameters

Operation	Parameter	Type	Required	Notes
CreateResource / ListProjectResources	project_id (path)	string (uuid)	yes	UUIDv7. Non-zero. Malformed → 400 invalid_project_id.
ListDomainResources	domain_id (path)	string (uuid)	yes	UUIDv7. Non-zero. The nil UUID → 400 invalid_domain_id.
GetResource / DeleteResource	id (path)	string (uuid)	yes	UUIDv7. Non-zero. Malformed → 400 invalid_resource_id.
ListProjectResources / ListDomainResources	cursor (query)	string	no	Opaque HMAC-signed continuation.
ListProjectResources / ListDomainResources	limit (query)	integer	no	[1, 200], default 50.

Schemas

The OpenAPI spec is the authoritative source for field shapes. The schemas this surface uses are:

• Request: ResourceCreateRequest (origin discriminator selects between the adopted and provisioned bodies).
• Response: ResourceResponse (single, with optional provisioning sub-object), ResourceList (paged).
• Embedded: ResourceProvisioning (provisioned_resource_id, phase).

The origin discriminator is a closed enum: adopted | provisioned. An adopted body sets kind and external_ref. A provisioned body sets kind, cloud_credential_id, blueprint_version_id, and a parameters map validated by the BlueprintVersion's parameter schema. A body whose origin is not in the closed set surfaces as 400 invalid_resource_origin.

ReBAC gates

Operation	Pre-condition	Schema permission	Object
Create (any origin)	pre-decode	project#deploy	project:<project_id>
Create (provisioned only)	post-decode, pre-persist	cloudcredential#use (subject is project:<project_id>; needs the Credential Assignment and a Cloud Assignment on the parent Cloud)	cloudcredential:<cloud_credential_id>
List (top-level)	pre-fetch	project#observe	project:<project_id>
List (per row)	post-fetch	resource#observe	resource:<id>
List by Domain (top-level)	pre-fetch	domain#read	domain:<domain_id>
List by Domain (per row)	post-fetch	resource#observe	resource:<id>
Get	pre-persist	resource#observe	resource:<id>
Delete	pre-persist	resource#manage	resource:<id>

The Create handler runs the project#deploy gate before decoding the body so a probe cannot exercise the JSON decoder. The provisioned flow layers a secondary cloudcredential#use check before the Resource row is persisted, so an unauthorised caller never produces a Resource row OR a broker-side ProvisionedResource. That secondary check uses the consuming project:<project_id> as its subject, not the calling user: the schema's uses relation admits only project (or project#operator) subjects, so the gate asks what the project may do rather than what the user may do.

The one check asks two questions, because the schema defines cloudcredential#use as (uses & parent->use) + owner + assigner. The project must hold both an approved Credential Assignment (which materialises cloudcredential:<id>#uses@project:<id>) and an approved Cloud Assignment on the credential's parent Cloud (which materialises cloud:<parent>#uses@project:<id>). A denial does not report which half is missing; the credential-assignment surface refuses a missing Cloud Assignment earlier, with 422 cloud_not_usable_in_project — see Credential Assignments.

Audit emission

Every grant and every denial emits an audit row through the transport-local AuditSink; the tenancy repository does NOT emit on writes. The relation strings are pinned in internal/transport/http/v1/resources/wiring.go:

• resource.create.adopted / resource.create.provisioned — granted, permission_denied, invariant_violation.
• resource.list — granted (carries item_count), permission_denied; the object is project:<id> on the Project list and domain:<id> on the Domain list.
• resource.get — granted, permission_denied.
• resource.delete.adopted / resource.delete.provisioned — granted, permission_denied, invariant_violation.

Error taxonomy

All error responses use the shared Problem envelope. The 403 path uses the richer PermissionDenied shape.

Code	Status	Where	Meaning
invalid_project_id	400	Create / List	Malformed or zero project_id.
invalid_domain_id	400	List by Domain	The nil UUID as domain_id.
invalid_resource_id	400	Get / Delete	Malformed or zero resource id.
invalid_resource_origin	400	Create	origin outside {adopted, provisioned}.
invalid_resource	400	Create	Aggregate invariant rejected the body (empty kind, provisioned-branch missing cloud_credential_id/blueprint_version_id, etc.).
invalid_body	400	Create	Body could not be read or did not parse as the typed request shape.
invalid_cursor	400	List	HMAC verification failed.
invalid_limit	400	List	Out of [1, 200].
unauthenticated	401	every operation	Request carries no authenticated principal.
cursor_binding_mismatch	403	List	Cursor was minted by a different caller; per-(caller, pepper) HMAC binding rejected the replay.
resource_not_found	404	Get / Delete	No Resource with the given id. The pre-persistence ReBAC gate returns 403; this surface returns 404 only after the gate has passed.
cloud_credential_not_found	422	Create (provisioned)	cloud_credential_id does not resolve.
blueprint_not_found	422	Create (provisioned)	blueprint_version_id does not resolve.
blueprint_provider_mismatch	422	Create (provisioned)	Both ids resolve, but the Blueprint version accepts none of the provider kinds corresponding to the provider of the Cloud behind the credential. Refused before the ProvisionedResource is minted; the Resource created for the request is removed again. errors[].field names both blueprint_version_id and cloud_credential_id, since either can be changed to make the pair provisionable.
request_body_too_large	413	Create	Body exceeded 8 KiB.
resources_not_provisioned	501	every operation	Composition root did not wire the Resources port.
internal	500	every operation	Server-side failure path.

Cross-references

• ../../../api/openapi/plexsphere-v1.yaml — OpenAPI 3.1 spec; the CreateResource, ListProjectResources, ListDomainResources, GetResource, DeleteResource operations and the ResourceCreateRequest / ResourceResponse / ResourceList / ResourceProvisioning schemas.
• ../../../internal/transport/http/v1/resources/ — the transport-tier implementation: the five handlers, the closed Problem.code taxonomy, the body-cap and limit-clamp constants, the per-row visibility filter, and the origin-branch dispatch.
• ../../../schema/authz.zed — ReBAC schema; the domain, project, resource, and cloudcredential definitions declare the gates this surface enforces.
• ./blueprints.md — companion surface for the Blueprint Catalog the provisioned flow consumes.
• ./authz.md — the PermissionDenied shape returned on 403.