# 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](https://relationship.service.m7.org/).

## 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](https://m7.org/docs/api/api.relationship.service.m7.org/authorization.md) before making
an integration. [Catalogue discovery](https://m7.org/docs/api/api.relationship.service.m7.org/discovery.md) 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:

```json
{
  "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

- [Authorization, token lifecycle and workspace selection](https://m7.org/docs/api/api.relationship.service.m7.org/authorization.md)
- [Project context, spaces and principal references](https://m7.org/docs/api/api.relationship.service.m7.org/scopes.md)
- [Current connections and resource memberships](https://m7.org/docs/api/api.relationship.service.m7.org/relationships.md)
- [Enrollment requests and terminal states](https://m7.org/docs/api/api.relationship.service.m7.org/enrollment.md)
- [Activity, mailbox delivery and acknowledgement](https://m7.org/docs/api/api.relationship.service.m7.org/mailbox.md)
- [Capability catalogue discovery](https://m7.org/docs/api/api.relationship.service.m7.org/discovery.md)