> For the complete documentation index, see [llms.txt](https://docs.openg2p.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openg2p.org/products/open-agri-stack/architecture/data-sharing-policies.md).

# Data-Sharing Policies

Policies that control data sharing.

Access policies say what a partner may ask for. In Agri Stack they are all held and approved in **Partner Management (PM)**, next to the partners' keys; the Consent Manager (CM) holds only consents. In a department the CM reads the scope policy from PM when it validates a consent; at the Exchange only the Composite reads the use-case policies, and the CM applies what the Composite sends. What a policy contains (its fields, versions and statuses, and how it is changed) is defined once, in Partner Management: [access policies](https://docs.openg2p.org/platform/platform-services/partner-management/functional-specifications.md#access-policies). This page explains how Agri Stack uses them.

## Two policies

Agri Stack uses both kinds of [access policy](https://docs.openg2p.org/platform/platform-services/partner-management/functional-specifications.md#two-kinds-of-policy) that Partner Management offers, one at the Exchange and one in each department:

* **The partner's use-case policy, at the Exchange.** Which use case a partner may call, for example `loan-profile@1`, and with what limits: the farmer ID types and signing algorithms allowed, the longest a consent may last, and whether the partner may present consents it signed. It lists no purposes: granting a use case grants its purpose ([decision #9](https://docs.openg2p.org/products/open-agri-stack/design-decisions.md#9-a-use-case-policy-does-not-list-purposes)). One policy per partner and use case, in the Exchange's Partner Management, approved by the Exchange's partner manager ([example policy](https://docs.openg2p.org/platform/platform-services/partner-management/api-reference.md#post-partners-requests-policy)). It lists no data: the use case defines that.
* **The Composite's scope policy, in each department.** Which of the registry's data the department allows the Composite to receive, for which purposes and farmer ID types. One policy per registry, in the department's Partner Management, approved by the department's partner manager ([how a registry applies it](#what-actually-gets-released)).

{% hint style="info" %}
**Partners and departments never deal with each other.** A partner has no policy in any department, and the Composite has no use-case policy: each department deals only with the Composite, and the Exchange with the partners.
{% endhint %}

### Use case, policies and consent

Four things together decide what a partner gets:

|                               | What it decides                                                                                 | Owned by                          | Kept in                                                                                                                                                                                                                  |
| ----------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Use case**                  | The data read from each registry (required and optional), the purpose and the response          | The Agri Stack platform team      | The [Composite](https://docs.openg2p.org/products/open-agri-stack/composite.md), as configuration (e.g. [`loan-profile.yaml`](https://github.com/OpenG2P/agri-stack/blob/develop/composite/use-cases/loan-profile.yaml)) |
| **Partner's use-case policy** | Whether the partner may call the use case, and its limits. Read only by the Composite           | The Exchange's partner manager    | The Exchange's Partner Management                                                                                                                                                                                        |
| **Composite's scope policy**  | The most each registry releases to the Composite                                                | Each department's partner manager | The department's Partner Management                                                                                                                                                                                      |
| **Consent**                   | The farmer's agreement to share data with this partner, for a purpose, with scopes per registry | The farmer                        | The Exchange's Consent Manager ([consent](https://docs.openg2p.org/products/open-agri-stack/architecture/consent.md))                                                                                                    |

The Consent Manager knows no use cases. The Composite publishes each use case granted to a partner as a [consent template](https://docs.openg2p.org/products/open-agri-stack/architecture/consent.md#consent-templates): the use case's purpose and scopes per registry, with the use-case policy's limits (farmer ID types, longest validity, partner-signed consents allowed). In the partner portal, staff choose one of the partner's templates; the consent records its purpose and scopes, and the template code as a label. Any use case with that purpose can use the consent. A consent the partner signs itself is accepted only if the use-case policy allows it: the Composite sends that limit to the Exchange CM at validate.

## What actually gets released

Through the Composite (path B in the [architecture](https://docs.openg2p.org/products/open-agri-stack/architecture.md#data-sharing-paths)):

**released = the use case's scopes (if the partner has a use-case policy for it) ∩ what the farmer consented to ∩ the Composite's scope policy in the department**

* **The Composite** refuses a partner that has no use-case policy for the use case.
* **The Exchange's CM** validates the consent against what the Composite sends: the use case's purpose and scopes, and the use-case policy's limits (subject ID type, signing algorithm, validity, partner-signed consents). It reads no policy. It puts, for each registry, the consent's grant ∩ the use case's scopes into that registry's signed **consent token**.
* **Each registry's own CM** checks the consent token and intersects it with the Composite's scope policy for that registry, read from the department's PM, and refuses it (`purpose_not_allowed`) if the policy does not list its purpose. A department therefore always decides what leaves its registry, and for which purposes.

The department never sees the use case's name: the consent token carries the **purpose** (a code from the country's `CONSENT_PURPOSE` dataset, e.g. `credit-assessment`), not `loan-profile`. So the department's policy lists purposes, and several use cases with the same purpose are covered by one entry. The purpose is the use case's own, declared in its file and shown by the Composite (`purpose` in the use case's description). The list of purposes is the `CONSENT_PURPOSE` dataset in each install's Master Data, loaded from the country pack. The Ethiopia pack's list (`credit-assessment`, `insurance-underwriting`, `subsidy-eligibility`, `program-enrolment`, `service-delivery`, `research-statistics`; codes and labels only, in [openg2p-data](https://github.com/openg2p/openg2p-data) `packs/ETH/codelists/consent_purpose.json`) is illustrative: each country sets its own, and a use case names one of them (`loan-profile`'s is `credit-assessment`). Read the list in the Master Data admin UI, or with the staff API (`POST /catalogue/get_list_values`, `list_code: CONSENT_PURPOSE`, a staff token). It is private by default; to let partners read it anonymously, a catalogue administrator [makes it public](https://docs.openg2p.org/platform/platform-services/master-data-service/admin-guide.md#make-a-dataset-public), and it is then at `/public/datasets/CONSENT_PURPOSE/entries` on the [public catalogue](https://docs.openg2p.org/platform/platform-services/master-data-service/public-catalogue.md).

* **The registry** releases only what is left, and only its own slice.

**The Composite's scope policy must cover every use case.** Partner Management does not know what a use case contains, so no scope policy is derived from the use-case policies automatically. Each department's scope policy for the Composite is the **superset** of what all published use cases read from its registry: every scope, required and optional, and every purpose. A new use case, or one that reads more, gets nothing extra from a registry until that department widens its scope policy; until then the registry withholds the scopes not covered, and denies the call if none of the requested scopes is covered (a mandatory source then fails the request). Widening is the department's decision: [when use cases change](https://docs.openg2p.org/products/open-agri-stack/administration/releasing-data-to-the-composite.md#when-use-cases-change).

<figure><img src="https://3034178245-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJZcdob2emEcLMvLyIxqT%2Fuploads%2Fgit-blob-b2cdad066606e0b4966f8a50cf3b2aa9047a7565%2Fopen-agri-stack-released-scopes.svg?alt=media" alt="Worked example: the use case asks for five scopes; the bank is granted the use case, so all five pass; the farmer declines land; the Livestock Department does not allow herd data; released: Farmer Registry personal details, Crop Sown crop season and measures"><figcaption><p>Worked example of released scopes</p></figcaption></figure>

{% hint style="info" %}
**A partner using one registry directly** (path A, no Composite): effective scopes = the partner's scope policy for that registry, in the registry's own PM ∩ the farmer's consent (held by the registry's CM, or signed by the partner if its policy allows).
{% endhint %}

{% hint style="info" %}
In the registries, a scope is a registry **data scope**: a named group of the registry's own fields, with ID `<controller>.<name>` (e.g. `farmer-registry.personal_details`, `crop-sown-registry.crop_season`). Each registry publishes its versioned catalogue at `POST /partner/data_scopes` (signed) and, unless turned off, an unsigned `GET` (which Partner Management reads for its policy form), and filters records to the consented fields before rendering them. See [Data Scopes](https://docs.openg2p.org/products/registry/registry/design/data-scopes.md), and the [Farmer Registry](https://docs.openg2p.org/products/registry/farmer-registry/data-scopes.md) and [Crop Sown Registry](https://docs.openg2p.org/products/registry/crop-sown-registry/data-scopes.md) scopes.
{% endhint %}

## Who approves what

| Change                                                                       | Who raises it, and how                                                                                                                                                                                                 | Approved in                                         |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| A partner joins the Exchange: its keys and a policy per use case it may call | The Exchange's partner manager, at the partner's request: an onboarding request                                                                                                                                        | The Exchange's PM                                   |
| A partner gets another use case                                              | The Exchange's partner manager: **Add policy** on the partner                                                                                                                                                          | The Exchange's PM                                   |
| A partner loses a use case                                                   | The Exchange's partner manager: **Revoke** that use case's policy                                                                                                                                                      | The Exchange's PM                                   |
| A new use case is published                                                  | The Agri Stack platform team ([creating a use case](https://docs.openg2p.org/products/open-agri-stack/composite/use-case-configuration.md#creating-a-use-case))                                                        | Not a policy change; partners still need it granted |
| The Composite may read more from a registry (a new scope or purpose)         | The department's partner manager: edits the Composite's scope policy ([Releasing Registry Data to the Composite](https://docs.openg2p.org/products/open-agri-stack/administration/releasing-data-to-the-composite.md)) | The department's PM                                 |
| A farmer consents, or revokes                                                | The farmer                                                                                                                                                                                                             | The Exchange's CM                                   |

Policy changes are versioned and audited in PM, and take effect when approved; modules see them within their policy cache time (about a minute by default).

## Fail closed

Every hop refuses when it cannot find a policy that allows the request:

| Hop           | No policy                                                                                                                                             | PM cannot be read                                                                                                                                   |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Composite     | `403 partner_not_allowed`: no policy for the use case                                                                                                 | The last answer is used for a while (up to six hours by default), then `503 partner_policy_unavailable`                                             |
| Exchange CM   | Reads no use-case policy: the Composite has refused the partner already. A consent outside the terms the Composite sends is denied (`consent_denied`) | Does not read policies. Consent templates: the Composite answers `503` when PM cannot be read, and the partner portal cannot make a consent (`503`) |
| Department CM | No scope policy for the Composite: the source is `denied`                                                                                             | As the Composite, then the source is `denied`                                                                                                       |

Partners are matched to PM by convention: `bank-a` → `PARTNER_BANK_A` ([partner ID convention](https://docs.openg2p.org/platform/platform-services/partner-management/functional-specifications.md#partner-id-convention)). How the CM evaluates a policy at validate time: [verification & enforcement](https://docs.openg2p.org/platform/platform-services/consent-management/design/verification-and-enforcement.md). How modules read policies from PM and cache them: [PM integration](https://docs.openg2p.org/platform/platform-services/partner-management/integration.md).

Checking a use case against these policies when it is published is planned: [Roadmap](https://docs.openg2p.org/products/open-agri-stack/roadmap.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.openg2p.org/products/open-agri-stack/architecture/data-sharing-policies.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.
