Each key carries a list of scopes, of the form resource:read or resource:write. Each operation requires one; a key without it gets 403 insufficient_scope and nothing is executed.
The 10 scopes
| Scope | Allows | Operations |
|---|---|---|
barometer:read | Read the price barometer (France and regions, five fuels). | GET /v1/barometer |
fuel-stations:read | List and read fuel stations, and the cheapest ones of a department. | GET /v1/fuel-stationsGET /v1/fuel-stations/cheapestGET /v1/fuel-stations/{id} |
charging-stations:read | List and read EV charging stations (IRVE). | GET /v1/charging-stationsGET /v1/charging-stations/{id} |
companies:read | Search and read establishments of the SIRENE directory. | GET /v1/companiesGET /v1/companies/{siret} |
fleet-costs:read | Compute a fleet's fuel and carbon overspend (nothing is stored). | POST /v1/fleet-costs |
simulations:read | List and read the organization's coverage simulations. | GET /v1/simulationsGET /v1/simulations/{id} |
simulations:write | Create a simulation, change its status, write its pitch. | POST /v1/simulationsPATCH /v1/simulations/{id}POST /v1/simulations/{id}/pitch |
prospects:read | List and read the organization's prospects, with their recomputed cost. | GET /v1/prospectsGET /v1/prospects/{id} |
prospects:write | Create, replace and delete prospects. | POST /v1/prospectsPUT /v1/prospects/{id}DELETE /v1/prospects/{id} |
geo:read | Geocode an address and compute a route (30 calls a minute). | GET /v1/geocodePOST /v1/routes |
write does not include read: an integration that creates prospects and reads them back asks for prospects:write and prospects:read. The list is closed: a scope that is not in it cannot be granted.
Choosing a key's scopes
Scopes are set when the key is created, with our team: tell us which ones each integration needs. To change them, a new key is created with the right scopes, then the old one is revoked.
The 403 insufficient_scope refusal
details.required gives the required scope, details.granted the key's scopes:
Response 403
{
"error": {
"code": "insufficient_scope",
"message": "This API key does not have the scope required by this route.",
"details": {
"required": "prospects:write",
"granted": [
"barometer:read",
"fuel-stations:read"
]
}
}
}