> 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/platform/platform-services/partner-management/creating-and-changing-policies.md).

# Creating and Changing Policies

Step by step in the Partner Management staff portal: give a partner an access policy (registry or use case), edit, widen or revoke it, approve the request, and check that PM serves it.

How a partner manager gives a partner an access policy and changes it later, in the Partner Management staff portal (`https://partner-management.<base domain>`, role `partner_manager`). What a policy is and the rules PM applies: [Access policies](https://docs.openg2p.org/platform/platform-services/partner-management/functional-specifications.md#access-policies).

The partner's PM ID is its ID upper-cased, `-` replaced by `_`, prefixed `PARTNER_` (`bank-a` → `PARTNER_BANK_A`).

## Filling in a policy

| Field                                             | Enter                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Empty means                                                | Enforced by (service)                                           |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------- |
| **Policy for**                                    | **Registry** for a scope policy (a partner of one registry); **Use case** for one use case of an Exchange (one policy per use case)                                                                                                                                                                                                                                                                                                                       | —                                                          | —                                                               |
| **Registry**                                      | Not free text: the registry's **Consent Data Controller** setting, exactly (e.g. `farmer-registry`), which is also the prefix of its scope IDs. A mismatch means the policy is never found and every request is denied                                                                                                                                                                                                                                    | Not allowed (scope policy)                                 | —                                                               |
| **Allowed scopes**                                | Full scope IDs from the registry's catalogue, e.g. `farmer-registry.land`: listed on the registry's **Data Scopes** page (e.g. [Farmer Registry](https://docs.openg2p.org/products/registry/farmer-registry/data-scopes.md), [Crop Sown Registry](https://docs.openg2p.org/products/registry/crop-sown-registry/data-scopes.md)), or read live from its partner API. Only these can ever be released, whatever the consent says                           | Not allowed                                                | The registry's Consent Manager                                  |
| **Use case**                                      | A published use case as `name@major`, e.g. `loan-profile@1`. A new major version needs its own policy                                                                                                                                                                                                                                                                                                                                                     | Not allowed                                                | The Exchange's Composite                                        |
| **Purposes**                                      | The codes the partner may give as a consent's purpose (`purpose.code`). When configured, a checklist of the country's dataset `CONSENT_PURPOSE` in the Master Data Service; otherwise free text agreed with the partner, e.g. `credit-assessment`. Registry policies only: a use-case policy has no purposes, because granting a use case grants its purpose (shown under the selected use case)                                                          | Any purpose                                                | Consent Manager                                                 |
| **Subject ID types**                              | The ID types the partner's consents may name the person by (`subject_id.type`). When configured, a checklist of the country's dataset `SUBJECT_ID_TYPE` in the Master Data Service; otherwise free text, spelt as the registries and partners use them, e.g. `FAYDA_FAN`, `FARMER_ID` in Agri Stack                                                                                                                                                       | Any type                                                   | Consent Manager                                                 |
| **Signing algorithms**                            | Pre-filled from the partner's keys (its active keys, or on onboarding the keys entered above): EC P-256 → `ES256`, Ed25519 → `EdDSA`, RSA → `RS256`. Add a second one only while the partner moves to a key of another type; one with no key is accepted with a warning                                                                                                                                                                                   | Not allowed                                                | Consent Manager (a consent signed otherwise is refused)         |
| **Max consent validity**                          | ISO-8601 duration, e.g. `P90D`, `P1Y`                                                                                                                                                                                                                                                                                                                                                                                                                     | No limit                                                   | Consent Manager                                                 |
| **Fetch type**                                    | `oneshot` (one query per consent) or `periodic` (repeated queries under one consent)                                                                                                                                                                                                                                                                                                                                                                      | `oneshot`                                                  | Recorded on the consent                                         |
| **Max fetch frequency**                           | For `periodic`, ISO-8601, e.g. `P1D`                                                                                                                                                                                                                                                                                                                                                                                                                      | —                                                          | Recorded only                                                   |
| **Data life**                                     | How long the partner may keep the data, ISO-8601, e.g. `P30D`                                                                                                                                                                                                                                                                                                                                                                                             | —                                                          | Recorded only (a contractual term)                              |
| **May collect consents by assisted confirmation** | Tick to let the partner's staff take a consent in the Consent Manager's partner portal with the person's national-ID login and one "I agree" tick, instead of a signed form and a Consent Approver ([scenario 0](https://docs.openg2p.org/platform/platform-services/consent-management/design/consent-collection.md#0-assisted-operator-confirmed)). The weakest proof: keep it for low-risk use cases. The Consent Manager install must also turn it on | Off: a signed form and an approver                         | Consent Manager (the partner portal does not offer it when off) |
| **May present its own signed consents**           | Tick only for a partner that collects consent in its own trusted system: the Consent Manager then accepts consents the partner signed itself. It cannot verify the person agreed, only the partner's signature                                                                                                                                                                                                                                            | Off: the partner uses consents held by the Consent Manager | Consent Manager (a partner-signed consent is refused when off)  |

For a **use case**, only the use case and the signing algorithm are needed, and there are no purposes: granting the use case grants its purpose. The subject ID types, validity, fetch type, data life, assisted confirmation and partner-signed consents are under **Optional limits**, folded: they only narrow what this partner may do with the use case. The Composite reads a use-case policy and passes its limits to the Exchange's Consent Manager with each request and in the use case's consent template; the Consent Manager does not read use-case policies.

**Enforced by** names the service that applies the field on every request, automatically; it is not a person's check (a Consent Approver checks a consent request collected in the partner portal, not the policy). "Recorded" fields are kept with the policy and the consent for audit; no module enforces them yet.

If the deployment has [catalogue sources](https://docs.openg2p.org/platform/platform-services/partner-management/functional-specifications.md#catalogue-sources), **Registry** and **Use case** are lists of the configured registries and the exchange's published use cases (**Other…** for any other), **Allowed scopes** a checklist of the registry's scopes. If a source (or the Master Data Service) cannot be read, its error is shown and the field is free text; the request then carries a warning for the approver. A dataset the country does not have is free text, without a warning.

## A new partner, with its policy

1. **Partners → + Onboard partner**: fill in the partner (Partner ID, Name, Organisation), its public key, and the **Reason for onboarding**.
2. Under **Policies (optional)**, click **+ Add policy** for each policy and [fill it in](#filling-in-a-policy): any mix, one per registry and one per use case.
3. **Submit request.** The keys and policies wait as `pending` until the request is approved.
4. [Approve the request](#approve-or-reject).

## An existing partner: add, edit or revoke

The partner must be `active` (its onboarding approved; a disabled partner is enabled first). Open it from **Partners**: **Policies** lists one row per policy (*Registry: …* or *Use case: …*) with its version, status and summary. Each action raises a policy request for one policy, applied when [approved](#approve-or-reject).

* **Add policy** — choose **Registry** or **Use case**, [fill it in](#filling-in-a-policy), give a **Description** and **Submit request.** To let a partner use another use case, add a **Use case** policy for it.
* **Edit** (on a row) — the form opens with the active version; change it and submit. The result is the policy's next version and replaces it whole, so to widen keep what is there and add to it.
* **Revoke** (on a row) — give a reason and click **Raise revoke request**.

A policy with a request waiting shows **Change pending** (a link to it) instead of **Edit** / **Revoke**; another change to it is refused (`PM-POLICY-409`) until that request is approved or rejected. Other policies are not blocked.

## Approve or reject

1. **Approvals** (the menu lists every request to onboard a partner, change its keys or change its policies), open the request. It shows the proposed keys, and the policies and revocations by registry or use case.
2. Check them against what was agreed with the partner (and, for a scope policy, with the registry's data owner).
3. **Approve** or **Reject**, with notes.

On approval each proposed policy becomes `active` (the previous version `superseded`) and each revoked one `revoked`; on rejection the proposed versions become `rejected`. Every step is in the partner's **History**.

## Check

* **In the portal:** the partner's page lists its **Policies**; **Show policy version history** shows every earlier version, its status and request.
* **What modules read:** PM's partner API, from inside the cluster (it has no login and is not public):

```bash
curl -s "http://commons-services-pm-partner-api/policies/PARTNER_BANK_A?data_controller=farmer-registry"   # a scope policy
curl -s "http://commons-services-pm-partner-api/policies/PARTNER_BANK_A?use_case=loan-profile@1"           # a use-case policy
curl -s "http://commons-services-pm-partner-api/policies/PARTNER_BANK_A"                                   # all of them
```

A `404` (`PM-POLICY-404`) means no active policy (or the partner is not active). Modules cache policies for up to a minute, so a change reaches them within about a minute ([Integration](https://docs.openg2p.org/platform/platform-services/partner-management/integration.md#6-consuming-access-policies)).

## By API

The same requests can be raised and approved with PM's staff API (a Keycloak token with the `partner_manager` role): `POST /partners/requests/onboarding` with `policies`, `POST /partners/requests/policy`, then `POST /partners/requests/{id}/approve`. Bodies and errors: [API Reference](https://docs.openg2p.org/platform/platform-services/partner-management/api-reference.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/platform/platform-services/partner-management/creating-and-changing-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.
