Skip to main content
A partner 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.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 or the template.The scope catalog lists every Reporter restriction. Read it with Retrieve a product’s scope catalog 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 or with the Identity API. 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 in the API guide, or in the Console. 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.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.
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:
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

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. For the refusals when you create or change a partner, see Error codes in the API guide.