Integration Scopes

Integration scopes define what data an API key is authorized to read. A client must hold the exact case-sensitive scope required by an endpoint, and the tenant's effective plan must enable that scope category. The current tenant controller assigns scopes during creation and does not expose a routed Edit action.

Available Scopes

ReportsRead

Grants read access to survey metadata and aggregate response summaries for the tenant.

What the ReportsRead scope covers:

GET /api/integrations/metadata/surveys.
GET /api/integrations/reports/surveys.
GET /api/integrations/reports/responses.

What the ReportsRead scope does not cover:

Usage summaries (requires UsageRead).
Individual response rows (requires RawResponsesRead).

UsageRead

Grants read access to tenant integration usage summary data.

What the UsageRead scope covers:

GET /api/integrations/reports/usage.

What the UsageRead scope does not cover:

Survey metadata or response data.

RawResponsesRead

Grants read access to individual response rows.

What the RawResponsesRead scope covers:

GET /api/integrations/reports/raw-responses.
Per-submission metadata and current file descriptors returned by the list endpoint.
GET /api/integrations/reports/raw-responses/{responseId}/answers for the actual answer values of one current tenant response, including file references but not file bytes.
GET /api/integrations/files/{answerFileId} for current authorized file associations.

Privacy considerations:

Raw response data may contain personal information. Grant this scope only when the integration contract explicitly requires individual-level data.
Ensure your data handling and storage complies with applicable data protection regulations.
All raw response queries are scoped to the tenant whose key is being used.

Scope Combinations

A single integration client may hold any combination of scopes. Typical combinations:

Use case	Recommended scopes
BI dashboard showing aggregate KPIs only	`ReportsRead`
Integration usage monitoring	`UsageRead`
Data lake ingestion requiring current row-level data	`ReportsRead`, `RawResponsesRead`
Compliance audit requiring individual records	`RawResponsesRead`

Apply the principle of least privilege: grant only the scopes the integration requires.

Scope Enforcement

Each Integration API endpoint checks its required scope after API-key authentication. A valid key without that scope returns 403 Forbidden with this BaseResponse; it does not identify the missing scope:

{
  "errorCode": 403,
  "errorMessage": "You do not have permission to access this resource.",
  "data": null
}

Scopes are stored on the integration client record and are separate from System and Tenant permission groups. ReportsRead and UsageRead require the Report API access plan capability; RawResponsesRead requires Raw response API access and uses the shorter configured maximum key lifetime.

Integration Scopes