Scopes

Ampere access has two layers:

Functional permissions — which classes of operations the caller’s role may perform.
Resource scope — which groups (and therefore which addresses and devices) the caller may touch.

A request can authenticate successfully and still fail with 403 when either layer denies access.

Functional permissions

Protected endpoints declare the permission they require. OpenAPI descriptions expose the required permission and which roles hold it.

Permission	What it unlocks
`READ_GROUPS`	List groups assigned to the caller
`READ_ADDRESS_INFORMATION`	Address-level group membership and related address information
`READ_SMARTMETER_DATA`	Smart meter registry, readings, intervals, forecasts
`READ_ENERGY_DATA`	Address-level P4 electricity and gas aggregates
`READ_SOLAR_DATA`	Solar inverter inventory, production, forecasts, schedule reads
`READ_CHARGER_DATA`	Chargers and charger consumption
`READ_VEHICLE_DATA`	Vehicles and charge/location/odometer state
`READ_BATTERY_DATA`	Batteries, charge state, forecasts
`READ_HVAC_DATA`	HVAC units and temperature state
`READ_GROUP_FLEX_DATA`	Group flex schedule reads and flex aggregation
`STEER_SOLAR_SCHEDULE`	Create and delete solar inverter schedules
`STEER_GROUP_BASED_FLEX`	Create and delete group flex schedules
`DYNAMIC_GROUP_MANAGEMENT`	Add or remove addresses in curtailment pools

Partners receive a role on their API user. The role determines the permission bundle. Exact role bundles are provisioned by Chargee; request only the capabilities your integration needs.

Resource scope

Most data endpoints are constrained by group assignment:

Callers see only groups they are assigned to (via GET /groups).
Address- and device-scoped routes succeed only when the address belongs to an accessible group.
Pool membership mutations require access to the target curtailment pool and ownership of the address through a partner group.

Practical model for partners

Question	Answered by
May this credential call this endpoint type?	Functional permission
May this credential see or change this address / group / device?	Resource scope
Why did a valid token get `403`?	Missing permission, or resource outside assigned groups

Integration guidance

Use least-privilege accounts (for example, separate read-only analytics from schedule-steering automation).
Discover accessible groups first with GET /groups, then navigate to addresses and devices.
Treat 403 as a configuration/provisioning issue, not a transient network failure.
Do not assume global portfolio access unless Chargee has explicitly provisioned it for that account.