> For the complete documentation index, see [llms.txt](https://docs.bosonnetwork.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bosonnetwork.io/core-concepts/federation.md).

# Federation

Federation is how independent super nodes come to know and trust each other. Federated nodes have verified each other's identity and exchanged descriptions of the services they run, and their services use that when they work across node boundaries - delivering a message to a user on another node, or fetching an object stored there - without any central hub.

## Why it is needed

Every node on the DHT can find every other node, but finding a node is not trusting it. Federation adds a verified relationship on top: each node has proved it holds its identity key and is reachable at the endpoints it announces, and each knows which services the other runs.

## The proposal flow

1. An administrator on node A proposes federation with node B, through A's [Admin API](/reference/http-api/director-admin.md#federation).
2. A looks B up in the DHT and **probes** it. Each side signs the same fresh nonce with its identity key, so both verify each other.
3. A sends a **proposal**. B verifies A the same way - DHT lookup, peer information, profile, probe - and decides within the same request.
4. If B accepts, the two nodes **exchange their service lists**.

The receiving node decides according to `federation.defaultProposalAction`:

* **`accept`** accepts any node that passes verification.
* **`decline`** declines every proposal. A node configured this way federates only with the nodes it proposes to itself.

A declined node must wait `declineCooldownPeriod` before proposing again. The protocol is described in the [Director Federation API](/reference/http-api/director-federation.md).

## Configuration

```yaml
# director.yaml
federation:
  enabled: true                  # default true
  defaultProposalAction: accept  # accept or decline
  declineCooldownPeriod: 3h      # default 24h; shipped 3h
```

Federation is **enabled** by default. With `enabled: false`, the node neither proposes nor accepts, and its federation endpoints answer `501 Not Implemented`.

## Node Information

A node describes itself to others with the `nodeInfo` block in `director.yaml` - name, logo, website and contact - which other nodes read from its `GET /api/v1/federation/info` and show in their admin dashboards.

## Services across nodes

Federation relationships are between Directors; the services build on them:

* **Photon Messaging** delivers messages for users of another super node to that node's messaging service, over its HTTPS federation interface, like mail relayed between servers. See [Built-in Services: Messaging](/core-concepts/services/messaging.md).
* **Ion Store** fetches objects stored on another node's Ion Store, verifies them against their content hash and caches them.

See [Service Federation](/build-services/service-federation.md).

## Blacklist

Independently of federation, the Director keeps a **blacklist** of misbehaving nodes. Nodes are added automatically for `blacklist.autoBanTime` (1 hour as shipped), or by an administrator. Blacklisted nodes are refused by the DHT and by federation.

## Managing Federation

Administrators propose, suspend and remove federation, and inspect nodes and proposals, through the Admin API; `boson-director-cli` lists nodes, their services and proposals. See [Federation Operations](/operate-a-node/federation-ops.md).

## Further Reading

* [Architecture Overview](/core-concepts/architecture.md)
* [Services Overview](/core-concepts/services.md)
* [Federation Operations](/operate-a-node/federation-ops.md)
* [Director Federation API](/reference/http-api/director-federation.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://docs.bosonnetwork.io/core-concepts/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.