insp.ac API

How scopes work

When you create an API key, you assign it one or more scopes. Each scope grants access to a specific set of API operations. A request using a key without the required scope is rejected with a 403 status.

Scopes are evaluated on every request. If a key has issues:read but not issues:write, it can list and retrieve issues but cannot create or update them.

Available scopes

Scopes follow a resource:action pattern. Current scopes include:

Scope	Grants
`issues:read`	List and retrieve issues
`issues:write`	Create and update issues
`works:read`	List and retrieve work orders
`works:write`	Create and update work orders
`sites:read`	List and retrieve sites
`sites:write`	Create and update sites
`assets:read`	List and retrieve assets
`assets:write`	Create and update assets
`users:read`	List and retrieve user profiles
`users:write`	Create and update user profiles
`checkins:read`	List and retrieve site check-ins
`checkins:write`	Create and update site check-ins
`logs:read`	List and retrieve logs/comments
`logs:write`	Create logs/comments
`sensors:read`	List and retrieve sensor readings
`sensors:write`	Ingest sensor readings
`templates:read`	List and retrieve templates
`templates:write`	Create and update templates
`runs:read`	List and retrieve inspection runs
`runs:write`	Create and update inspection runs
`schedules:read`	List and retrieve unified schedule occurrences
`schedules:write`	Update occurrence status and obligation links
`calendar:read`	List calendar-formatted schedule occurrences
`media:write`	Upload and complete media attachment flows
`integrations:read`	List integration-platform action/trigger/subscription catalogs
`integrations:write`	Create and delete integration-platform trigger subscriptions

Note

A full list of scopes and the operations they protect is available in the interactive reference for each endpoint.

Scope violations

When a request requires a scope that the API key does not have, the API returns a 403 Forbidden response. This is a permanent error for that key configuration — retrying will not help.

403 response body

{
  "error": "Insufficient permissions",
  "code": "FORBIDDEN"
}

Important

A 403 from scope enforcement is different from a 401 authentication failure. If you receive 403, the key is valid but does not have the right permissions. Update the key's scopes in your organization settings.

Least-privilege guidance

Follow these practices to minimize the blast radius if a key is compromised:

Create separate keys for separate integrations, each with only the scopes it needs.
Prefer read-only scopes for reporting and analytics integrations.
Only add write scopes to keys used by systems that create or modify resources.
Audit scope assignments periodically and remove scopes that are no longer required.

Scopes and SDKs

SDK clients inherit the scopes of the API key used at initialization. Calling an SDK method for an operation the key cannot access will surface the 403 error through the SDK's standard error handling.

Handling scope errors (TypeScript)

try {
  await client.issues.create({ title: "New issue", status: "open" });
} catch (err) {
  if (err.status === 403) {
    console.error("API key is missing issues:write scope");
  }
}