Relationship Service API

Relationship Service stores scoped connections between principals and membership of resources, together with enrollment requests and delivery receipts. Use it from a trusted application backend to maintain a relationship graph and present relationship events to your users. Your application remains responsible for authenticating its users, obtaining consent and deciding what a relationship means for access to its own resources.

API base: https://api.relationship.service.m7.org/v1/. Manage projects, spaces, project access and mailbox views in the Relationship application.

Authorization

Protected requests use Authorization: Bearer ACCESS_TOKEN with an unbound M7 access token for audience https://api.relationship.service.m7.org. The caller needs active receiving-service admission and active access to the selected project's Management group. Project capabilities apply to every operation; graph and enrollment mutations additionally require project Owner or Admin. An organization workspace uses the organization's project access and current organization grants while preserving the actual caller as actor.

Read authorization and workspace boundaries before making an integration. Catalogue discovery is public and needs no token.

Requests and responses

Protected routes documented here use POST with Content-Type: application/json and a JSON object body. Unknown operation fields are rejected. UUID references must be non-nil dashed UUID strings; returned UUIDs are normalized to uppercase. Replace every *_UUID and credential placeholder in these examples with your own authorized reference or credential.

Successful protected responses use this envelope:

{
  "status": 1,
  "comment": "relationship service",
  "data": {
    "project_id": "PROJECT_UUID",
    "items": [],
    "next_offset": null
  }
}

data depends on the operation. A failure has status: 0, a human-readable comment and data.code. Check the HTTP status and the body; business and admission errors preserve the corresponding HTTP error code. Admission failures can also include data.reason.

Body code Meaning and action
400 Invalid fields, types, references or scope input; correct the request.
401 Missing or invalid caller credential; obtain a valid access token.
403 Admission, project membership, role or capability denied; resolve access.
404 Record absent or outside the selected scope; recheck the mapping.
409 Stale version, duplicate with changed input, or completed request conflict; reload before retrying.
5xx Storage or authorization dependency unavailable; preserve the request identity and retry with backoff.

Comments are for display and diagnosis, not stable machine error identifiers.

Pagination and versions

Graph, scope, enrollment and activity lists accept integer count (1–200, default 100) and nonnegative integer offset (default 0, at most PHP_INT_MAX - 201). They return items and nullable next_offset; they do not return a total count. Mailbox lists default to 50 and also return total_count and has_more. Keep the same project, scope and filters when following a page. These are offset lists, so concurrent changes can shift rows; deduplicate by record ID.

Save, remove and request-decision operations use the record's current positive integer version. After a conflict, reload and reconsider the action before sending the new version. Removal also requires an exact confirmation ID.

Integration guides