> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beaconrevenue.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Access and grants

> What a reader grant states, which readers read which copy of your data, the four ways they connect, and what a request outside a grant returns.

Anything reading Beacon from outside connects through a **reader grant**: one authorisation naming the reader, what it may read, how fresh, sealed or live, where the data goes, and until when. Each rule below states the model, the mechanism behind it, and how to verify it.

<Note>
  This page describes a designed model, not shipped behaviour. The grant form and all four connection paths are specified and unbuilt. The limits enforced today are on [Boundaries](/boundaries).
</Note>

## The reader grant

A grant is issued per reader, not per key. One grant governs every path that reader uses.

| Field               | What it states                                      |
| ------------------- | --------------------------------------------------- |
| Reader identity     | What is connecting, and who owns it                 |
| Reader class        | Whether the reader is yours or outside your company |
| Resource scope      | Which families of information it may read           |
| Entity scope        | All accounts, or one segment, region or book        |
| Seal mode           | Sealed figures only, or live values too             |
| Freshness floor     | How stale is too stale to answer                    |
| Sensitivity ceiling | How sensitive a figure the reader may reach         |
| Destination         | Where the data goes                                 |
| Expiry              | Until when                                          |

**Mechanism:** the grant is a guided form in your own permission screens. Beacon proposes a configuration and has no path to apply one. **Verify:** open a grant and read it back — every field is stated, none inferred from another.

## Reader classes

Three classes. Each reads its own separately built copy of your data.

| Reader                                           | Reads                                                                        |
| ------------------------------------------------ | ---------------------------------------------------------------------------- |
| Beacon's own reasoning                           | Your full data, bounded by the role of the person asking                     |
| Your own systems and agents                      | Your data without person-level records; live figures where your grant allows |
| Investors, advisors, anyone outside your company | Sealed figures only. No live figures, no person-level records                |

**Mechanism:** restricted information is absent from the copy an external reader reads, excluded when that copy is built rather than removed per request. **Verify:** a request for an excluded figure returns the same refusal however it is phrased.

## The four connection paths

| Path                       | Protocol                         | Direction       |
| -------------------------- | -------------------------------- | --------------- |
| Assistant connection       | MCP                              | The reader asks |
| Read interface             | REST, on a version-pinned schema | The reader asks |
| Event stream               | Webhook, or subscribe            | Beacon sends    |
| Fields on your own records | Your tool's own API              | Beacon sends    |

A path changes the transport and the audience. It never changes the figure, its definition, or the reader's ceiling.

**Mechanism:** all four serve one stored set of values; none holds a calculation of its own. **Verify:** request one figure over two paths — same number, same calculated-at stamp.

## Published retrievals

The retrieval set is closed and published. It grows by versioned, documented additions.

| Retrieval                | Returns                                                                       |
| ------------------------ | ----------------------------------------------------------------------------- |
| What this grant may read | The reader's own ceiling, so it discovers rather than probes                  |
| Definition               | The versioned definition of a figure, segment or lifecycle stage              |
| Figure                   | One value for a scope and period, sealed or live                              |
| Account intelligence     | Segment, fit band, lifecycle stage, health, renewal risk, expansion readiness |
| Account list             | The working list, filtered by segment, stage or risk                          |
| Segment model            | The dimensions, weights and thresholds, as a portable object                  |
| Target and Plan context  | What the company committed to this period, and where the gap sits             |
| Path                     | The projected path for an account, with its confidence                        |
| Events since             | The pull equivalent of the event stream                                       |
| Explanation              | Provenance, source state, and the article behind the figure                   |

**Mechanism:** no retrieval accepts an expression or a free-text query. **Verify:** the table above is the whole surface; a call outside it fails rather than assembling a total. [Boundaries](/boundaries) states why no query interface exists.

## Requests outside a grant

A request beyond the grant is refused whole and logged. It is never partly served, never trimmed to fit, and never answered with a narrower figure standing in for the one asked for.

**Mechanism:** scope is checked before retrieval, so a failing request produces a reason and what would make the value available, not a value. **Verify:** the access log lists every request and its disposition, refusals included. The refusal reasons are listed in [Boundaries](/boundaries).

## Revocation and expiry

Every grant carries an expiry. Revoking one fails the reader's next request.

**Mechanism:** revocation applies at the source with no propagation delay, and nothing held on the reader's side is treated by Beacon as still valid. **Verify:** revoke a grant, then repeat that reader's last call — it returns a refusal, not a stale figure.

<Warning>
  Granting live values, or raising the sensitivity ceiling, widens what the destination sees for as long as the grant runs. A figure written onto a record in your own tool is visible to everyone with a seat in that tool and cannot be re-scoped afterwards.
</Warning>

## Reader grants and agent permissions

Two objects, two screens. A reader grant states what someone else's software may read out of Beacon. Agent permissions state what Beacon's own agents may do inside your systems.

**Mechanism:** separate objects on separate surfaces; neither widens the other. **Verify:** revoking a reader grant changes no agent permission, and removing an agent's permission changes no reader grant.

## What a granted read returns

No figure is served bare, on any path, to any reader.

| Attached to every figure | Content                                                 |
| ------------------------ | ------------------------------------------------------- |
| Definition               | Which definition produced it, and its version           |
| Source state             | Which systems it came from, and their state at the time |
| Calculated at            | When it was last calculated                             |
| Freshness                | Whether that is current against the grant's floor       |
| Seal                     | Sealed or live                                          |
| Confidence               | How sure it is                                          |
| Sensitivity              | Which handling class it falls under                     |

**Mechanism:** the response is assembled with the figure and cannot be requested without it. **Verify:** count the fields on any response — a figure arriving alone is a defect, not a compact form.

Related: [Boundaries](/boundaries) · [Connector catalogue](/connector-catalogue) · [Data model](/data-model/overview)