API keys
A partner API key identifies your introducer account, carries its scopes and determines its data perimeter. This page covers its whole lifecycle.
Anatomy of a key
Code
The prefix is readable and stable. The secret is not: it is shown once, at creation. Instafuel only keeps a fingerprint and cannot give it back. Lose it and you rotate the key.
Getting a key
Keys are not self-provisioned: Instafuel issues them when your introducer account is opened, after the partnership agreement is signed.
-
Ask for the account through your Instafuel contact.
-
Receive your test key (
ifp_test_*). It is immediate and commitment-free: build and validate your whole integration with it. -
Ask for the production key (
ifp_live_*) once your integration is ready. Instafuel will ask for your servers' outbound IP addresses and the scopes you need, and will hand you the production base URL along with the key.
Scopes
A key only carries the scopes it was granted. Ask for the minimum you need — that is what limits the damage if it leaks.
| Scope | Allows |
|---|---|
COMPANIES_READ | read the companies in your portfolio |
COMPANIES_WRITE | request a company onboarding, update a record |
USERS_READ | read your clients' web accounts |
USERS_WRITE | create and update web accounts at your clients |
WALLET_READ | read Fuelz balances and follow your payment declarations |
LEDGER_READ | read a wallet's entries |
TRANSACTIONS_READ | read fill-ups |
DRIVERS_READ | read driver wallets — contains personal data |
ALERTS_READ | read alerts for portfolio companies |
REPORTS_READ | read the portfolio summary |
CREDIT_REQUEST_WRITE | upload proof and declare a payment (never credit directly) |
A call outside the key's scopes returns 403 PAPI_SCOPE_MISSING and has no effect. The message names the missing scope, so you know at once what to ask for.
GET /v1/papi/me returns, at any time, the scopes the calling key carries and the ones Instafuel has authorised on your account. You cannot grant yourself a scope beyond that ceiling — key creation refuses it with 422 PAPI_SCOPE_ABOVE_CEILING.
One key per use
Separate things that do not carry the same risk: a read-only key for your internal dashboard, a write key for your onboarding back office. The day one leaks, you revoke it without stopping the rest.
IP restriction
A production key can be limited to a list of outbound IP addresses. A call from any other address is refused with 403 PAPI_IP_FORBIDDEN, even with a valid key.
This is the most effective protection against an exfiltrated key: the secret alone is no longer enough, the call must also come from your infrastructure.
Warn Instafuel before changing hosting provider or adding an egress gateway — otherwise the cut is immediate and total.
Rotation
Rotate production keys at least once a year, and immediately if one may have been exposed: accidental commit, lost laptop, contractor leaving.
Rotation is zero-downtime, provided you keep the order:
-
Ask for a new key. The old one stays active.
-
Deploy the new one in your configuration. Check with
GET /v1/papi/methat it answers200from your production servers. -
Run both for a while, long enough for every process to have reloaded its configuration — scheduled jobs and queue workers included, they are usually the last.
-
Revoke the old one and check that no
401 PAPI_KEY_INVALIDshows up in your logs.
Order matters
Revoking before deploying cuts your integration until the next deployment. A revoked key is never reactivated.
Revocation
Ask your Instafuel contact for revocation, quoting the key prefix — never the whole key in an email.
Revocation is immediate and final. Any call presenting the key then returns 401 PAPI_KEY_INVALID.
If a leak is confirmed, revoke first and investigate second: a compromised key gives a complete view of your portfolio and can onboard companies in your name.
Hygiene
- Store the key in a secret manager, or at least in an environment variable. Never in the repository.
- Add a filter to your logs: a key copied into a stack trace is a published key.
- Never send a key by email or chat. Use an encrypted, one-time channel.
- Log the prefix your outbound calls use (
ifp_live_9f2c…). During an incident, you will know which one to revoke. - On staging, treat the test key as disposable: a leak costs little there, which is not a reason to expose it.