Project scopes and principal references

Configure a project and its spaces in the Relationship application, then retain the resulting project, space and optional subspace IDs in your integration. Use these reads to verify that mapping before graph or enrollment commands.

Routes

All routes use POST under https://api.relationship.service.m7.org/v1/, with the Bearer and workspace contract.

Route	Required fields	Optional fields	Capability and result inside data
/projects/context	project_id	—	project.view; project, membership, management_group_id, capabilities.
/projects/spaces/list	project_id	method, count, offset	space.list; project_id, items, next_offset, can_manage, capabilities.
/projects/subspaces/list	project_id, space_id	count, offset	space.list; project_id, items, next_offset, space.

IDs are non-nil dashed UUID strings. method is exactly pairwise or resource_membership; omitting it lists both. Paging follows the common count/offset rules.

curl --fail-with-body --silent --show-error \
  --request POST 'https://api.relationship.service.m7.org/v1/projects/spaces/list' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"project_id":"PROJECT_UUID","method":"resource_membership","count":100,"offset":0}'

Space records include id, project_id, code, name, method, direction, metadata and integer version. Subspaces include id, project_id, space_id, code, name, metadata and integer version; they inherit their space's method and direction. Use IDs for commands; names and metadata are display or application data.

Scope semantics

Graph and enrollment commands require project_id and space_id. subspace_id is an optional UUID string; omission or null selects the space root. It does not include all subspaces. Root and subspace records are independent, with one level of subspaces and no membership inheritance.

Space method	Relationship meaning
pairwise, mutual	Two distinct principals; A↔B and B↔A identify the same bond.
pairwise, directed	A→B and B→A identify separate bonds.
resource_membership, directed	One principal belongs to the exact selected space root or subspace.

Keep each consumer resource's mapping explicit. Metadata does not prove ownership, authenticate an external resource or assign access in your service. The same principals can have independent bonds in different scopes.

Principal reference

{
  "namespace": "example.app",
  "principal_id": "PERSON_UUID"
}

Field	Required	Type and limit
namespace	Yes	Nonempty UTF-8 string, at most 128 bytes; comparison is case-sensitive.
principal_id	Yes	Non-nil dashed UUID string, normalized to uppercase.

The object accepts only those two fields. Choose a stable namespace and UUID mapping for your own principals and derive them from authenticated application context. Relationship does not resolve usernames, verify the principal exists in your application or infer consent from its UUID.

Pairwise commands require both source and target references and reject self-connections. Membership commands require source; omit target because the selected scope is the resource. Stored records return source_ref and target_ref (null for resource membership). Mutual pairwise records may return their endpoints in canonical order, independent of the submitted order.

Metadata and missing scopes

Metadata is a JSON object, up to 65,536 encoded bytes and 64 JSON levels. Keys have application-defined meaning; metadata does not grant permissions. An omitted metadata field on save preserves the existing object; {} clears it. Invalid methods or references return body code 400. A missing space or a subspace belonging to another space returns body code 404. A project may deny access with body code 403 before revealing its records.

Deleting a scope in the management application removes its current relationships and finalizes pending requests. Retain history as events, and do not reuse an old mapping as though the deleted scope still exists.