Authentication and access
Authenticate with a static API key in the X-API-Key header. Key format, what a key can access, and what each 401 and 403 code means.
Send your API key in the X-API-Key header on every request. That is the whole authentication model: no login, no tokens, no refresh. A request is accepted only when the key is active, API integration is enabled on your account, the account has an active charging profile, and the request comes from an allowed IP address.
The API key
Every request to the Integration API carries a static API key in the X-API-Key header:
GET /api/v1/integration/transactions?from=...&to=... HTTP/1.1
Host: prod-app.octanetech-api.com
X-API-Key: oct_live_a1b2c3d4_Gk7fP2xQ9vLm3nRt8wYb5cHj6sDz1eAu4iFo0pNq| Property | Detail |
|---|---|
| Format | oct_live_<prefix>_<secret> in production, oct_test_<prefix>_<secret> on staging |
| Lifetime | The key does not expire on its own. It stops working only when Octane switches it off, or when your account loses access (see below). |
| Rotation | The key's value never changes. If a key is compromised, Octane switches it off and issues a new key with a new prefix. |
| Storage on Octane's side | Only a SHA-256 hash of the key is stored. Octane cannot recover a lost key; a new one is issued instead. |
| Scope | One customer account, including all of its corporate groups and corporates. |
Keep the key server-side
Never embed the key in a mobile app, browser code or a public repository. Send it only over HTTPS, and only from the IP addresses on your allow-list.
The key prefix
The <prefix> segment (for example a1b2c3d4) is not secret. Octane uses it to identify your key in logs and in support conversations. Quote it when you contact Octane about a key; never send the full key.
What can a key access?
The customer account is always derived from the key, never from request parameters. A key can only read its own customer's transactions. If you filter by corporate_id or corporate_group_id, the values must belong to your account; anything else returns 404.
If your organisation has several customer accounts with Octane, each one needs its own key.
When is a request accepted?
A request succeeds only when all of the following are true, in this order:
- The request comes from an allowed IP address. Otherwise
403 IP_NOT_ALLOWED. See Network and rate limits. - The key is within its rate limit. Otherwise
429 RATE_LIMITED. - The key is valid and active. Otherwise
401 INVALID_API_KEY. The same code is returned whether the key is unknown or switched off. - API integration is enabled on your account. Otherwise
403 API_INTEGRATION_NOT_ENABLED. - Your account has an active, unexpired charging profile. Otherwise
403 NO_ACTIVE_CHARGING_PROFILE.
Rules 4 and 5 also decide whether webhooks are sent: if either fails, deliveries stop until access is restored.
Access expiry
When your charging profile has an end date, successful responses include an X-Access-Expires-At header with that date in ISO 8601. Access ends at exactly that moment unless the profile is renewed. Monitor this header and renew ahead of time to avoid an interruption.
HTTP/1.1 200 OK
Content-Type: application/json
X-Access-Expires-At: 2026-12-31T21:59:59ZWhat do the 401 and 403 codes mean?
| Status | Code | What to do |
|---|---|---|
401 | INVALID_API_KEY | Check the header name and value. If the key was switched off, ask Octane for a new one. |
403 | API_INTEGRATION_NOT_ENABLED | Ask your Octane account manager to enable API integration on your account. |
403 | NO_ACTIVE_CHARGING_PROFILE | Your account has no active charging profile, or it has expired. Contact Octane. |
403 | IP_NOT_ALLOWED | The request came from an IP that is not on your allow-list. Send the new IP to Octane. |
403 | EDGE_NOT_ENFORCED | An Octane-side configuration issue. Contact Octane support with your key prefix and the request_id. |
All errors share the same error shape.
Keys and environments
Production keys (oct_live_) work only against the production host; staging keys (oct_test_) work only on staging. See Environments.
Common questions
- How do I authenticate with the Octane Integration API?
- Send your API key in the X-API-Key header on every request over HTTPS. There is no login, token or refresh flow. Keys are issued by Octane and look like oct_live_<prefix>_<secret>.
- Does the API key expire?
- No. A key works until Octane switches it off or your account loses access, for example when API integration is disabled or your charging profile expires. The key value never changes.
- Why am I getting 401 INVALID_API_KEY?
- The X-API-Key header is missing, the key is unknown, or the key has been switched off. The same code is returned in all three cases. Check the header, then ask Octane whether the key is active.
- Why am I getting 403 NO_ACTIVE_CHARGING_PROFILE?
- Your account has no active, unexpired charging profile with Octane. Contact your account manager to renew it. Access resumes immediately once a profile is active.
- Can one API key access several corporates?
- Yes. A key covers the whole customer account, including every corporate group and corporate in it. Filter with corporate_id or corporate_group_id if you only want part of it.