> For the complete documentation index, see [llms.txt](https://help.resouris.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.resouris.com/part-2-running-resouris/federation.md).

# Share cover between organisations

**Federation** lets two ReSouris tenants — two trusts, or a trust and a partner provider — agree to lend each other staff. It is the organisation-level counterpart to [lending staff between departments](/run-the-roster/cross-department-cover.md): the same problem one tier up, where neither side administers the other.

Because it crosses an organisational boundary, it is not something one administrator can simply switch on. It is a **signed bilateral agreement**, and both sides have to sign.

**Where:** proposals at `/ui/admin/federation/proposals`; the register of live agreements at `/ui/admin/federation`.

## The two permissions, and why they are two

| Permission                  | Lets you                                                                       |
| --------------------------- | ------------------------------------------------------------------------------ |
| `cross_tenant.cover_offer`  | Propose a federation, sign as the inviting tenant, and terminate an agreement. |
| `cross_tenant.cover_accept` | Accept a federation proposed by somebody else.                                 |

Both are held by `tenant_admin` by default, and they are deliberately separate so a tenant can grant them to different people. **Offering to share your staff and agreeing to take on somebody else's are two different administrative responsibilities**, and an organisation may well want the second to need a different signature from the first.

## The lifecycle

A proposal moves through states, and nothing takes effect until both signatures are in:

```
proposed ──sign (inviter)──┐
                           ├──> both_signed ──> active
proposed ──accept (invitee)┘

proposed ──reject──> rejected
active ──terminate──> terminated
```

* **Propose** — the inviting tenant names the other tenant and the **kind**:
  * `bidirectional` — both sides may draw on the other.
  * `a_offers_to_b` — one-way. The inviting tenant lends; the invited tenant does not reciprocate.
* **Sign** and **accept** are the two signatures, one per side. Who signed what is recorded on the proposal, not inferred.
* When both are in, the proposal advances and an entry appears in the **agreement register** at `/ui/admin/federation`, which is the list of what is actually in force.
* **Terminate** ends a live agreement. **Reject** declines a proposal that was never active.

> ⓘ **The proposal and the agreement are separate records on purpose.** The proposal is the negotiation — who asked, who signed, when, and whether it was declined. The agreement is the live permission. Keeping both means a terminated agreement still has its origin story, which is what you need when somebody asks next year why two organisations were sharing staff.

> ⚠️ **Terminating is not retrospective.** It stops future cover. Rosters already published under the agreement stand, and the audit trail still explains them — which is correct, because the work actually happened.

## Related

* Within one tenant, use [cross-department cover](/run-the-roster/cross-department-cover.md) instead — it needs no signatures, only `cross_department_cover.write`.
* Deployment-level context for multi-tenant installs is in [Deployment modes](/part-2-running-resouris/deployment-modes.md).
* Who holds what: [Roles and access](/part-2-running-resouris/permissions.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.resouris.com/part-2-running-resouris/federation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.