> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Partners in Reporter > Confine a partner's Reporter credential to the institutions or to the templates you choose, tell it how to name them on each request, and read the refusals it receives. A [partner](https://docs.lerian.studio/en/platform/access-manager/features/partners/overview) can call Reporter with its own credential. In Reporter, you confine that credential to some institutions, to some templates, or to both. This page shows how to choose that scope, what each choice reaches, and what the partner receives when it goes outside it. Every Reporter partner needs a scope: at least one institution or one template. ## Step by step *** **1. Choose what the partner works with** Pick the narrowest scope that covers what the partner needs. Each row is a restriction you can add. The **API field** is the `field` of a scope entry; the Console shows the name in the first column. | Restriction | API field | What the partner reaches | What it is refused | | - | - | - | - | | **Institution** | `institutionId` | The reports of its own institutions: creating them, listing them, and reading and downloading them by ID under the institution. The institution's own record. Subscribing its institutions to regulatory documents, and generating their filings. | Other institutions, a report that names no institution, the list of institutions, templates, and every route that reads a report by ID without naming the institution. | | **Template** | `templateId` | Its own templates and their content. The reports of its own templates: creating them, listing them, and reading and downloading them by ID under the template. | Other templates, a report that names no template, the list of templates, institutions, generating regulatory filings, and every route that reads a report by ID without naming the template. | The two restrictions can be combined. A partner restricted by both names an institution and a template in its scope on every request on reports, and reads a report by ID only under both. Each value is the ID that Reporter returns when you create the [institution](https://docs.lerian.studio/en/products/reporter/console/managing-institutions.md) or the template. The scope catalog lists every Reporter restriction. Read it with [Retrieve a product's scope catalog](https://docs.lerian.studio/en/reference/platform/access-manager/retrieve-a-product-s-scope-catalog.md) for `reporter`. Some rules apply to every scope: * A request that does not name an item of a restricted type is refused when it acts on reports. For example, a partner restricted to some institutions cannot list all the reports of your tenant. * A query that lists several values is refused when any one of them is outside the scope. A body field takes one value: a list in it is refused with `400`. * Routes that act on the whole tenant are refused to every partner: data sources, deadlines, metrics, events, the lists of templates and institutions, the regulatory catalog, regulatory subscriptions and mappings, and the corrections, approval, and provenance of a regulatory filing. **2. Give the partner its permissions and scope** Create the partner, or change it, in the [Console](https://docs.lerian.studio/en/platform/access-manager/features/partners/console.md) or with the [Identity API](https://docs.lerian.studio/en/platform/access-manager/features/partners/api.md). The product slug is `reporter`. * Add at least one scope entry for Reporter. Without one, Access Manager refuses the partner with `400` and `IDE-1060`. * Check the resources and actions. The most you can give is what the `reporter-editor-role` role holds in your tenant. Access Manager checks each write you give against the scope. A write that acts on the whole tenant is never given to a partner, and is refused with `400` and `IDE-1056`. The Console marks the line **Outside the scope**. In Reporter, these writes are: * Creating, changing, or deleting templates, data sources, deadlines, and institutions. * Changing or deleting a regulatory subscription and its mapping. * Approving a regulatory filing (`regulatory-approval`). The writes a partner can receive are `reports` with `post`, to generate reports, and `regulatory` with `post`, to subscribe its institutions and generate their filings. **3. Create its Reporter application** Create the partner's application with the product `reporter`. See [Create the partner's applications](https://docs.lerian.studio/en/platform/access-manager/features/partners/api.md#create-the-partners-applications) in the API guide, or [in the Console](https://docs.lerian.studio/en/platform/access-manager/features/partners/console.md#create-the-partners-applications). Send the client ID and the client secret to the partner through a secure channel. **4. Tell the partner how to name its items** On the routes that read one report, the path carries the institution, the template, or both, depending on the route the partner picks. On the other routes, the partner names them in the queries and bodies that Reporter already has. Only the restrictions the partner has are checked: each value it names for one of them must be inside its scope. A partner restricted only by template can name any institution. | Routes | Writes | Reads and routes by ID | | - | - | - | | Reports: `/v1/reports` | To create: body `institution` and `templateId` | To list: query `institution_id` or `institutionId`, and `template_id` or `templateId` | | Reports by ID: `/v1/institutions/{institutionId}/reports/{id}`, `/v1/templates/{templateId}/reports/{id}`, `/v1/institutions/{institutionId}/templates/{templateId}/reports/{id}`, each also with `/download` | None: the routes only read | Path `institutionId` for a partner restricted by institution, `templateId` for one restricted by template, and both for one restricted by both | | Institutions: `/v1/institutions/{institutionId}` | None: the writes are never given to a partner | Path `institutionId` | | Templates: `/v1/templates/{templateId}`, `/v1/templates/{templateId}/content` | None: the writes are never given to a partner | Path `templateId` | | Regulatory filings: `/v1/regulatory/subscriptions`, `/v1/institutions/{institutionId}/regulatory/reports` | To subscribe: body `institution`. To generate a filing: path `institutionId`, and body `subscriptionId` with a subscription of that institution | None: the reads act on the whole tenant | A partner reads one report by ID only through the routes that name its institution or its template. `GET /v1/reports/{id}` and its `/download` are refused to every partner. To generate a filing, a partner uses `/v1/institutions/{institutionId}/regulatory/reports`. `POST /v1/regulatory/reports` is refused to every partner. A report of another institution or another template, asked for under the partner's own path, answers `404` with `RPT-0011`. This is the same answer as for an ID that does not exist. The same applies to a regulatory subscription of another institution, sent under the partner's own institution. > [!WARNING] > > What the partner sees in a report is what the template and the data source read. Reporter confines the rows to an institution only through the institution's scope: the rows of each data source that belong to it. Before you give a partner an institution, check that the institution's scope names its rows in every data source its templates read. > > A partner restricted only by template is not confined to an institution: it can generate its templates for any institution. Give such a partner templates and data sources made only for it. If a partner reads rows that are not its own, the template, the data source, or the institution's scope is set up wrong. It is a setup error, not an authorization error, and the fix is in that setup. **5. Confirm that it works** This check assumes the partner has the `reports` resource with the `get` action on Reporter, and a scope restricted to one or more institutions. Use the partner's credential. Read a report of an institution inside its scope. The answer is `200`: ```bash theme={null} REPORTER_BASE_URL="https://reporter." # your Reporter base URL REPORTER_BEARER_TOKEN="paste-the-partner-access-token-here" INSTITUTION_ID="paste-an-institution-id-in-the-scope-here" REPORT_ID="paste-a-report-id-of-that-institution-here" curl -s -o /dev/null -w '%{http_code}\n' \ -H "Authorization: Bearer ${REPORTER_BEARER_TOKEN}" \ "${REPORTER_BASE_URL}/v1/institutions/${INSTITUTION_ID}/reports/${REPORT_ID}" ``` Send the same request with an institution outside the scope. The answer is `403`. To see the code, drop `-o /dev/null`: the response body carries `AUT-1020`. ## If something fails *** | Code | Status | What it means | What to do | | - | - | - | - | | `AUT-1020` | 403 | The request is outside the partner's permissions or outside its scope, or it does not name an item the scope requires. | Check that the request names its institution or its template in the field of that route, with a value in the partner's scope. Check also that the partner has the permission for that route. | | `RPT-0011` | 404 | The report or the regulatory subscription does not exist, or it belongs to another institution or template than the one the path names. Nothing is read or changed. | Check the ID, and the institution or template in the path. | | No code | 400 | A body field received a list of values. | Send one institution or one template in the field. | | `AUT-1009` | 401 | The partner is suspended. | Reactivate the partner. | | `AUT-1010` | 401 | The request is outside the partner's validity window. | Change the validity window. | The answer does not say whether the permissions or the scope refused the request. This is on purpose: a partner cannot use a refusal to learn which institutions or templates exist outside its scope. For every other code, see the [Reporter error list](https://docs.lerian.studio/en/reference/products/reporter/reporter-error-list.md). For the refusals when you create or change a partner, see [Error codes](https://docs.lerian.studio/en/platform/access-manager/features/partners/api.md#error-codes) in the API guide. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.