> 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/administration/managing-partners.md).

# Managing Partners

Onboarding and managing partners.

How the Exchange's partner manager lets a partner (a bank, an insurer, an agritech) use Agri Stack, and stops it. All partner decisions are made in the **Exchange's** Partner Management (`https://partner-management.<Exchange's base domain>`); the departments never onboard the Exchange's partners. Why it works this way: [Use Cases](https://docs.openg2p.org/products/open-agri-stack/architecture/use-cases.md).

## Onboard a partner

1. **Agree terms** with the partner outside the system: the use cases it may use, purposes, data retention.
2. **Onboard it in Partner Management** with its public key and a policy for each use case it is assigned ([Creating and Changing Policies](https://docs.openg2p.org/platform/platform-services/partner-management/creating-and-changing-policies.md#a-new-partner-with-its-policy)). Its partner ID is its own ID upper-cased with the prefix `PARTNER_` (`bank-a` → `PARTNER_BANK_A`).
3. **Approve** the onboarding request. Partner Management lets the person who raised a request approve it; in production, have another person approve every onboarding, key and policy request.
4. **Partner portal accounts** for its staff, if they will collect consents in the portal ([below](#partner-portal-accounts)).

The partner's own steps: [Partner Guide: Fetching Farmer Data](https://docs.openg2p.org/products/open-agri-stack/partner-integration-guide.md).

## Assign or remove a use case

* **Assign another use case:** on the partner's page, **Add policy** → **Use case**, enter it (`name@major`, e.g. `loan-profile@1`), submit, approve. Only the use case is required. A use-case policy lists no purposes: granting the use case grants its purpose. Subject ID types, longest consent and partner-signed consents are optional limits (empty means no further limit), and the signing algorithm is pre-filled from the partner's keys. The limits also appear in the use case's consent template in the partner portal.
* **A wrong use case name:** if Partner Management reads the Composite's use cases ([Exchange install](https://docs.openg2p.org/products/open-agri-stack/deployment/exchange.md#commons-services)), **Use case** is a list and an unknown name is refused (`PM-POLICY-400`). Without that source the field is free text: a misspelt name (`loan-profil@1`) is accepted and, once approved, grants nothing. The Composite refuses the partner's calls for the intended use case (`403 partner_not_allowed`) and the partner portal offers no template for it. Revoke the wrong policy and add the right one.
* **Remove a use case:** **Revoke** on that use case's policy, give a reason, approve. The Composite refuses the partner's requests for that use case from then on, and the partner portal no longer offers its consent template; its other use cases are unaffected, including those with the same purpose, which can still use its consents.

Steps and fields: [Creating and Changing Policies](https://docs.openg2p.org/platform/platform-services/partner-management/creating-and-changing-policies.md).

## Disable a partner

To stop a partner altogether, for example when its agreement ends:

1. **Disable it in Partner Management:** the partner's page → **Disable** ([Disabling and Enabling a Partner](https://docs.openg2p.org/platform/platform-services/partner-management/disabling-a-partner.md)).
2. **Disable its staff's partner portal accounts** ([partner portal accounts](#partner-portal-accounts)). Disabling the partner already stops their requests from going anywhere; this also stops them logging in.

Every service then refuses the partner: the Composite refuses its queries (so no consent tokens are issued for it), and the partner portal offers its staff no consent template. Its consents stay recorded but can no longer be used. A partner that also calls a registry directly is refused there only if it is disabled in that department's Partner Management too. This applies once the services' caches expire: within about a minute for policies and five minutes for keys ([what happens](https://docs.openg2p.org/platform/platform-services/partner-management/disabling-a-partner.md#what-happens)).

## Enable it again

The partner's page → **Enable**, and re-enable its portal accounts in Keycloak. Its keys, use cases and unexpired consents work again as they were.

## Partner portal accounts

Partner staff who collect farmers' consents log in to the [partner portal](https://docs.openg2p.org/platform/platform-services/consent-management/partner-portal.md) (`https://consent-partner-portal.<Exchange domain>`) with an account in the Exchange's Keycloak, realm `partner`. The install creates the realm, its client and roles and the `partner_id` attribute; each account is created by hand. A partner needs accounts only if its staff collect consents in the portal.

**Create an account.** In Keycloak (`https://keycloak.<Exchange domain>`), realm **partner**:

1. **Users → Add user**: a username (e.g. `bank-a-operator`), the user's **Email**, **First name** and **Last name** (Keycloak requires them: left empty, the user must fill them in at first login), **Email verified** on. In the attribute **Partner ID** (`partner_id`), the partner's ID as it signs requests: `bank-a`, not `PARTNER_BANK_A`. **Create**.
2. **Credentials → Set password**: a password the user changes at first login (**Temporary** on).
3. **Role mapping → Assign role → Filter by clients**: `consent-partner-portal` **PARTNER\_OPERATOR** (or **PARTNER\_ADMIN**; the Consent Manager treats them alike today).

The portal then offers the user only the consent templates of the use cases assigned to that partner. Without the **Partner ID** attribute, or with a role from another client, the user can log in but every request is refused.

**Disable or remove an account.** The user → **Enabled** off; or **Action → Delete**. The consents the user collected stay with the partner.


---

# 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/administration/managing-partners.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.
