API integration guide

Overview

The FuelBoss API provides secure access to your company’s operational data including nominations, operations, documents and webhooks for real-time notifications. This RESTful API is designed for enterprise integration and follows industry-standard security practices.

API integration flow

The diagram below illustrates a typical integration sequence showing how your system authenticates, creates nominations, monitors operations, retrieves documents, and receives real-time updates via webhooks:

Sequence diagram showing a typical FuelBoss API integration: authentication, nomination creation, operation monitoring, document retrieval, and webhook notifications

Environments

The FuelBoss API is available in the following environments:

Production: https://api.fuelboss.net - Live environment with real operational data
Demo: https://api.demo.fuelboss.net - Sandbox environment for testing and integration development

Interactive Swagger/OpenAPI documentation is available at /swagger/index.html for each environment to explore endpoints and view schemas. Contact itops@ofiniti.com for environment access and credentials.

Authentication

The FuelBoss API uses OAuth 2.0 Client Credentials Grant for API authentication. This flow is designed for server-to-server communication where your system authenticates directly with our API.

Getting access credentials

Contact FuelBoss itops@ofiniti.com to receive your:

client_id - Unique identifier for your company
client_secret - Secret key for authentication (keep secure)

Token request

Endpoint: POST /oauth/token Request Headers:

Content-Type: application/x-www-form-urlencoded

Request Body:

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Success Response (200 OK):

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Error Response (400 Bad Request):

{
  "error": "invalid_request",
  "error_description": "grant_type is required"
}

Using the access token

Include the access token in all API requests: Request Headers:

Authorization: Bearer YOUR_ACCESS_TOKEN

Token Lifecycle:

Validity: 60 minutes (3600 seconds)
Renewal: Request new token before expiration
Scope: Automatically limited to your company’s data

Conventions

All endpoints return JSON and require a valid access token unless otherwise specified.

This guide covers concepts and workflows. The API reference section of this tab documents every endpoint’s request and response schema — including field-level descriptions and enumeration values — and includes an interactive playground.

Date and time formats

All dates and times sent to the API must be in ISO 8601 format with an explicit UTC offset — a numeric offset such as +08:00 or -04:00, or Z for UTC:

2026-07-06T14:00:00+08:00
2026-07-06T14:00:00-04:00
2026-07-06T14:00:00Z

The offset you send is honored as-is: the value is interpreted as an absolute instant and stored in UTC. Timestamps without an offset (e.g. 2026-07-06T14:00:00 or 2026-07-06) are rejected with 400 Bad Request. Unless suffixed with Utc, dates and times returned by the API are expressed in the local time zone of the bunkering port, with the port’s UTC offset included (e.g. 2026-07-06T14:00:00+02:00 for a port in CEST). Fields suffixed with Utc (e.g. lastChangedAtUtc) are always returned in UTC.

Nominations

Nominations represent requests for bunkering operations. You identify a nomination by its clientReference — your unique identifier, at most 100 characters, alphanumeric and hyphens only (a-z, A-Z, 0-9, -) — and the create-or-update endpoints are idempotent on it. All timestamps you send must include an explicit UTC offset — see Date and time formats. Create and update nominations through the endpoint matching your role: as a supplier (PUT /v1/nominations/supplier) or as a receiver (PUT /v1/nominations/receiver). As a receiver, your authenticated company is used as the receiver — the receiver section has no companyIdentifier — and you identify the supplier with supplierCompanyIdentifier; supplierCompanyEntityReference is only applied for loading operations where the receiver and supplier are the same company and is ignored otherwise. Field-level semantics for every request and response body are documented on the corresponding API reference page. Draft nominations are lightweight, in-progress nominations: when creating or updating a draft (PUT /v1/nominations/drafts), only operationStandardCode, laycanStart, and laycanEnd are mandatory, and everything else can be filled in later through subsequent upserts or directly in the FuelBoss web app. Retrieving drafts (GET /v1/nominations/drafts) is paginated with an opaque cursor (cursor and limit query parameters; default 50, maximum 200 per page).

PATCH /v1/nominations/{clientReference}/schedule (reschedule) is deprecated. Use the create-or-update endpoints to change scheduling information instead: delivery.estimatedTimeOfBunkering and delivery.estimatedBunkeringDurationInMinutes cover rescheduling, and supplier.assetIdentifier covers supplier asset changes. The endpoint remains functional for backward compatibility but will be removed in a future version.

Nominations with an asset operator

An asset operator is a company that manages bunkering assets (vessels or terminals) on behalf of another company. FuelBoss lets these relationships be modelled on a nomination so the operator can work on it. Use Get Asset Operator Companies to discover which relationships exist for your company and which company entities each relationship allows. There are two directions, both driven by the supplier section of the Create or Update Nomination (Supplier) (PUT /v1/nominations/supplier) and Create or Update Draft Nomination (PUT /v1/nominations/drafts) requests: 1. You are the supplier and appoint an asset operator. You create the nomination for your own company (leave supplier.companyIdentifier empty, or set it to your own company) and set supplier.assetOperatorCompanyIdentifier to a company you have appointed as your asset operator. That company then gains the ability to view and edit the nomination. The appointed company must appear in the myAssetOperators list returned by Get Asset Operator Companies. If you also provide supplier.companyEntityReference, it must be one of the entities that relationship allows.

{
  "supplier": {
    "companyIdentifier": "COMP-123",
    "assetOperatorCompanyIdentifier": "COMP-OPERATOR-1",
    "companyEntityReference": "ENT-SUPPLIER-01"
  }
}

2. You act as the asset operator for another company. You create the nomination on behalf of a company you operate assets for by setting supplier.companyIdentifier to that company and providing a supplier.companyEntityReference that the relationship allows. The supplier company you name must appear in the companiesIAmOperatorFor list returned by Get Asset Operator Companies, and the companyEntityReference is required and must be one of that company’s allowed entity references. Your own company is recorded as the asset operator; if you also send assetOperatorCompanyIdentifier, it must equal your own company identifier.

{
  "supplier": {
    "companyIdentifier": "COMP-SUPPLIER-2",
    "companyEntityReference": "ENT-ALLOWED-07"
  }
}

When a supplier company, asset operator company, or company entity reference cannot be resolved to an allowed relationship, the request is rejected with 422 Unprocessable Entity.

Entity management

Contracts and entities provide reference data you attach to nominations. Contracts can be referenced from nominations via the contractReference field in the nomination’s delivery details. Contracts are idempotent on reference (alphanumeric and hyphens only, at most 100 characters). A contract has a name, an optional external reference, an optional type (term or spot) and price type (floating or fixed), optional UTC start and end dates, and optional scoping lists: supplier entity references, port UN/LOCODEs, counterpart company identifiers, and counterpart entity references. Counterpart entities are also idempotent on reference. email must be a valid email address (at most 320 characters) and phoneNumber may contain only digits, spaces, and the characters + - ( ). The returned shapes are documented on the Get Company Entities and Get Counterpart Entities reference pages.

Operations

Operations represent actual bunkering operations that have started or completed. Retrieve an operation with the same client reference that created the corresponding nomination — the response includes bunker delivery notes and document references. Each entry in the operation’s documentReferences array can be retrieved individually — the response body is the binary file, and the content type varies by document (PDF, JPEG, PNG). A merged PDF of all documents is available for operations signed using FuelBoss InBrowser™ signing.

Webhooks

Webhooks allow you to receive real-time notifications about events in the FuelBoss system.

Creating subscriptions

Create a subscription (POST /v1/webhooks) for the event types you list (see CloudEvent types for the available values). A company can have at most 10 subscriptions, and the endpoint URL must use HTTPS.

The secret field is optional but recommended: FuelBoss uses it to sign every delivery — see Webhook security.
The headers field configures custom HTTP headers included in every delivery, useful for authenticating with API gateways such as Azure API Management (for example Ocp-Apim-Subscription-Key). At most 10 headers; keys up to 100 characters, values up to 1000 characters. The reserved names X-Webhook-Signature, X-Event-Id, X-Event-Type, User-Agent, and Content-Type cannot be used. Header values are write-only: responses return the configured names via headerKeys but never the values.
Subscribe using the simple event type values (for example nomination_cancelled). Deliveries carry the full CloudEvents format in the type field (for example net.fuelboss.nomination.cancelled) — see CloudEvent types for the mapping.

Webhook delivery format

When events occur, FuelBoss sends POST requests to your registered webhook URLs using the CloudEvents v1.0 specification format. Each webhook delivery contains a CloudEvent envelope with standardized fields (specversion, id, type, source, time, datacontenttype) and the event-specific payload in the data field. The envelope, the request headers, and the payload of every event — including field-level descriptions and a realistic example — are documented on the webhook event reference pages. Important Notes:

All webhook deliveries use POST method with Content-Type: application/json
The id field identifies the event: retries of the same event carry the same id, so use it for idempotency checking
The type field uses CloudEvents format. See CloudEvent Types for the mapping between subscription values and delivery type strings
Field names inside the data payload are PascalCase (for example ClientReference), unlike the camelCase field names used by the REST API endpoints
Timestamps are always in ISO 8601 format with UTC timezone
Your webhook endpoint must respond with 2xx status code within 10 seconds
Failed deliveries are retried with exponential backoff for up to 24 hours
Any custom headers configured on the subscription are included in every webhook delivery alongside the standard headers
Webhook deliveries originate from fixed IP addresses per environment. If your firewall or API gateway requires IP allowlisting, use the following addresses:
- Production: 72.144.19.232
- Demo: 9.141.22.123

CloudEvent types

Mapping between webhook subscription event types and CloudEvent delivery type strings:

Subscription Value (when creating webhook)	CloudEvent Type (in delivery `type` field)	Description
nomination_created	net.fuelboss.nomination.created	Nomination has been created
nomination_cancelled	net.fuelboss.nomination.cancelled	Nomination has been cancelled
nomination_bunkering_location_changed	net.fuelboss.nomination.bunkering_location.changed	Nomination bunkering location has changed
nomination_fuel_specification_changed	net.fuelboss.nomination.fuel_specification.changed	Nomination fuel specification has changed
nomination_receiver_vessel_changed	net.fuelboss.nomination.receiver_vessel.changed	Nomination receiver vessel has changed
nomination_supplier_asset_changed	net.fuelboss.nomination.supplier_asset.changed	Nomination supplier asset has changed
nomination_bunkering_start_time_changed	net.fuelboss.nomination.bunkering_start_time.changed	Nomination estimated bunkering start time (BST) has changed
nomination_bunkering_end_time_changed	net.fuelboss.nomination.bunkering_end_time.changed	Nomination estimated bunkering end time (estimated time of completion) has changed
nomination_contract_changed	net.fuelboss.nomination.contract.changed	Nomination contract has changed
nomination_company_entity_changed	net.fuelboss.nomination.company_entity.changed	Nomination supplier company entity has changed
nomination_counterpart_entity_changed	net.fuelboss.nomination.counterpart_entity.changed	Nomination counterpart entity has changed
nomination_draft_upserted	net.fuelboss.nomination.draft.upserted	Draft nomination has been created or updated
operation_started	net.fuelboss.operation.started	Bunkering operation has started
operation_ended	net.fuelboss.operation.ended	Bunkering operation has ended

Note: When creating webhook subscriptions, use the simple subscription values (left column). When processing webhook deliveries, parse the CloudEvent type strings (middle column) from the type field. Each subscription value links to the reference page documenting that event’s delivery, envelope, and payload.

Webhook security

Signature verification

When creating a webhook subscription with a secret, FuelBoss signs each webhook delivery with HMAC-SHA256. The signature is included in the X-Webhook-Signature header as a Base64-encoded string. To verify a webhook delivery:

Extract the X-Webhook-Signature header value
Compute HMAC-SHA256 of the raw request body using your secret
Base64-encode the computed hash
Compare the computed signature with the header value (use constant-time comparison)

Best practices

Always use HTTPS URLs for webhook endpoints
Verify webhook signatures to ensure authenticity
Use the CloudEvent id field for idempotency to handle duplicate deliveries
Respond with 2xx status code quickly (under 10 seconds)
Process webhook payloads asynchronously if needed
Log webhook deliveries for debugging and audit purposes
Implement exponential backoff if you need to retry processing
Configure firewall or API gateway IP allowlisting for webhook source IPs (see Webhook Delivery Format)

Error handling

HTTP status codes

Code	Description
200	Success
201	Created - Resource successfully created
204	No Content - Resource successfully deleted
400	Bad Request - Invalid request format (e.g. a timestamp missing an explicit UTC offset)
401	Unauthorized - Invalid or expired token
403	Forbidden - Insufficient permissions
404	Not Found - Resource does not exist
409	Conflict - Resource conflict (e.g., duplicate)
422	Unprocessable Entity - Valid format but fails business validation
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Contact support

Error response format

ProblemDetails Response: All error responses use the RFC 9457 (Problem Details for HTTP APIs) format with the following fields:

Field	Type	Description
type	string	URI reference identifying the problem type
title	string	Short, human-readable summary of the problem type
status	number	HTTP status code
detail	string	Human-readable explanation specific to this occurrence
instance	string	URI identifying the specific API instance
errors	object	Validation errors by field name (only for validation failures)
timestamp	string (ISO 8601)	When the error occurred in UTC
trace_id	string	Request identifier for tracing and correlation

Example - Validation Error (422):

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.23",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "One or more validation errors occurred in the request.",
  "instance": "/v1/nominations/supplier",
  "errors": {
    "ClientReference": ["The ClientReference field is required."],
    "FuelSpecifications": ["At least one fuel specification is required."]
  },
  "timestamp": "2026-03-10T12:34:56Z",
  "trace_id": "00-abc123-def456-00"
}

Example - Timestamp Without UTC Offset (400):

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The timestamp '2026-07-06T14:00:00' must include an explicit UTC offset, for example '2026-07-06T14:00:00+02:00', '2026-07-06T14:00:00-04:00', or '2026-07-06T14:00:00Z'.",
  "instance": "/v1/nominations/supplier",
  "timestamp": "2026-03-10T12:34:56Z",
  "trace_id": "00-abc123-def456-00"
}

Example - Not Found (404):

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Not Found",
  "status": 404,
  "detail": "Nomination with client reference 'NOM-2025-999' was not found.",
  "instance": "/v1/nominations/NOM-2025-999",
  "timestamp": "2026-03-10T12:34:56Z",
  "trace_id": "00-abc123-def456-00"
}

Example - Internal Server Error (500):

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.6.1",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred",
  "instance": "/v1/nominations/supplier",
  "timestamp": "2026-03-10T12:34:56Z",
  "trace_id": "00-abc123-def456-00"
}

Rate limiting

Limits:

Rate: 100 requests per minute per client_id
Window: Rolling 60-second window
Scope: Applied per company credentials

Rate Limit Headers: All responses include rate limiting information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1730293200

Rate Limit Exceeded Response (429):

{
  "type": "https://httpstatuses.com/429",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please retry after 60 seconds.",
  "traceId": "00-abc123-def456-00"
}

Security and compliance

Transport security

TLS/HTTPS Only: All communication must use HTTPS
Certificate Validation: Verify SSL certificates
Token Security: Store client credentials securely (never in source code or client-side applications)

Audit logging

FuelBoss logs all API requests for security and compliance:

Timestamp of request
Client ID and Company ID
Endpoint accessed and HTTP method
Response status code and response time
IP address and user agent

Data access

Company Isolation: API responses limited to your company’s data only
No Cross-Company Access: Cannot access other companies’ information
Data Retention: Audit logs retained per compliance requirements

Webhook security

When configuring webhooks:

Use HTTPS endpoints only
Provide a secret for HMAC signature verification
Verify webhook signatures on your server
Implement idempotency to handle duplicate deliveries
Allowlist webhook source IP addresses in your firewall (see Webhook Delivery Format)

Versioning

Version strategy

Current Version: 1.0 (accessible via /v1 URL prefix)
URL Format: https://api.fuelboss.net/v1/...
Semantic Versioning: Non-breaking changes will be added to v1
Breaking Changes: Will result in new major version (/v2, /v3, etc.)

Version lifecycle

Support Period: Minimum 6 months for previous version
Deprecation Notice: 3 months advance notice before deprecation
Migration: Migration guides provided for breaking changes

For the history of changes in each release, see the changelog.

Support

Technical support

Email: itops@ofiniti.com
Response Time:
- General inquiries: 24 hours
- Critical issues: 4 hours

Monitoring and status

Planned Maintenance: 48-hour advance notice via email
Incident Communication: Subscribe via our status page (email, Slack, Microsoft Teams, or RSS)
API Status: Monitor via our status page at https://ofiniti.statuspage.io/ (machine-readable JSON at https://ofiniti.statuspage.io/api/v2/summary.json); subscribe there for incident and degradation notifications

Guides

API Reference

Changelog

Overview

API integration flow

Environments

Authentication

Getting access credentials

Token request

Using the access token

Conventions

Date and time formats

Nominations

Nominations with an asset operator

Entity management

Operations

Webhooks

Creating subscriptions

Webhook delivery format

CloudEvent types

Webhook security

Signature verification

Best practices

Error handling

HTTP status codes

Error response format

Rate limiting

Security and compliance

Transport security

Audit logging

Data access

Webhook security

Versioning

Version strategy

Version lifecycle

Support

Technical support

Monitoring and status

​Overview

​API integration flow

​Environments

​Authentication

​Getting access credentials

​Token request

​Using the access token

​Conventions

​Date and time formats

​Nominations

​Nominations with an asset operator

​Entity management

​Operations

​Webhooks

​Creating subscriptions

​Webhook delivery format

​CloudEvent types

​Webhook security

​Signature verification

​Best practices

​Error handling

​HTTP status codes

​Error response format

​Rate limiting

​Security and compliance

​Transport security

​Audit logging

​Data access

​Webhook security

​Versioning

​Version strategy

​Version lifecycle

​Support

​Technical support

​Monitoring and status

Overview

API integration flow

Environments

Authentication

Getting access credentials

Token request

Using the access token

Conventions

Date and time formats

Nominations

Nominations with an asset operator

Entity management

Operations

Webhooks

Creating subscriptions

Webhook delivery format

CloudEvent types

Webhook security

Signature verification

Best practices

Error handling

HTTP status codes

Error response format

Rate limiting

Security and compliance

Transport security

Audit logging

Data access

Webhook security

Versioning

Version strategy

Version lifecycle

Support

Technical support

Monitoring and status