Scope
The partner API exposes one surface, /v1/papi/*. Your key gives access to your portfolio, and nothing else.
The rule
Scope comes from the key, never from the request
No operation accepts a scope identifier from the body or the query to widen what you can see.
A companyId parameter is always a narrowing filter: it is intersected with your actual portfolio. If it falls outside, the answer is 403 — never silence, never someone else's data.
With a portfolio holding companies 4832 and 4790, an unfiltered call covers both:
A companyId from the portfolio narrows the view — 200, company 4832 only:
A companyId outside the portfolio is refused, without leaking anything about the company:
Note the 404: the response does not say whether company 5001 exists. A 403 would have confirmed it, and a stolen key could then have enumerated the platform's companies.
Same principle on writes: scope fields present in a request body are ignored, not honoured. Onboarding a company always attaches it to your portfolio, whatever introducer identifier you send.
Three levels of restriction
A request goes through three successive filters. Each can refuse it:
| Level | Question | Refusal |
|---|---|---|
| Key | is the key valid, active, called from an allowed IP? | 401, 403 PAPI_IP_FORBIDDEN |
| Scopes | does the key carry the scope this operation needs? | 403 PAPI_SCOPE_MISSING |
| Portfolio | does the target resource belong to your portfolio? | 404 COMPANY_NOT_FOUND |
Scopes (COMPANIES_READ, COMPANIES_WRITE, CREDIT_REQUEST_WRITE, REPORTS_READ) are covered in API keys.
403 or 404?
The rule is simple, and has no exception on this API:
403— you are identified, but the key lacks the requested scope, or the call comes from an unauthorised address, or your account is closed. The problem is your authorisation.404— the resource does not exist or is not in your portfolio. Both cases are deliberately indistinguishable.
A 404 on an identifier you believe valid therefore usually means it belongs to someone else. This is deliberate: probing the API must not let anyone map other people's data.
What is not exposed
The partner API gives no access to stations, fuel brands, platform settings, or the data of a company that has left your portfolio. Those surfaces exist for other actors and are not public.
An operation that does not appear in the API reference is not reachable with an ifp_* key, whatever URL you try.
What your clients see on their side
The accounts you create for your clients — fleet manager, finance director — sign in to the Instafuel dashboard with their own password. They see their company, not your portfolio, and have no access to the partner API.
Conversely, your key does not let you act as one of those accounts. See Roles.