API reference

Overview

Base URL

https://api.petronyx.net/api/v1

Format

JSON request and response bodies, UTF-8

Auth

Bearer access token, refreshable

Tenancy

Scoped to the signed-in user's company

curl https://api.petronyx.net/api/v1/health

{"success":true,"data":{"status":"ok","timestamp":"2026-10-02T08:15:00.000Z"}}

Authentication

Sign in with POST /auth/login. A successful response carries accessToken, refreshToken, expiresIn and tokenType. Send the access token on every other call as Authorization: Bearer <token>.

curl -X POST https://api.petronyx.net/api/v1/auth/login \
  -H "content-type: application/json" \
  -d '{"email":"you@company.com","password":"your-password"}'

Two-factor challenge

When two-factor sign-in is on, login returns challengeName and a short-lived session instead of tokens. Complete it with the six-digit code from the authenticator app.

curl -X POST https://api.petronyx.net/api/v1/auth/verify-mfa \
  -H "content-type: application/json" \
  -d '{
    "email": "you@company.com",
    "session": "<session from the login response>",
    "challengeName": "SOFTWARE_TOKEN_MFA",
    "code": "123456"
  }'

Refreshing and signing out

Exchange the refresh token for a new pair before the access token expires. Each sign-in is a device session; users can revoke sessions from security settings, after which its tokens stop working.

curl -X POST https://api.petronyx.net/api/v1/auth/refresh \
  -H "content-type: application/json" \
  -d '{"refreshToken":"<refresh token>"}'

Responses and errors

{
  "success": true,
  "data": { },
  "meta": { }
}

{
  "success": false,
  "statusCode": 400,
  "requestId": "6f1c...",
  "timestamp": "2026-10-02T08:15:00.000Z",
  "path": "/api/v1/stations",
  "method": "POST",
  "error": {
    "statusCode": 400,
    "message": ["name must be a string"],
    "error": "Bad Request"
  }
}

Authentication and identity

Sign in, two-factor challenges, token refresh, sessions and the current user.

• /authLogin, MFA verification, refresh, password reset, recovery codes and logout
• /identityIdentity overview, system users, roles and permissions
• /securitySecurity policy, role requirements, status and device sessions

Workspace

Company onboarding and the guided setup wizard.

• /tenantsCompany workspaces and their configuration
• /onboardingOnboarding requests for new companies
• /workspace-setupSetup wizard progress, saved step by step

Stations and forecourt

The physical model every calculation depends on.

• /stationsStations, locations and status
• /stations/{stationId}/tanksTanks, capacity and fuel grade
• /pumpsPumps with devices, documents and external mappings
• /nozzlesNozzles and the tank each one draws from
• /fuel-gradesFuel grade catalogue, specifications and documents
• /stations/{stationId}/mediaStation photos and media

Shifts and stock

The daily loop: shifts, readings, reconciliation and the stock sheet.

• /shiftsShifts with assignments, attendance and handover
• /shift-templatesRepeating shift patterns
• /meter-reading-sessionsOpening and closing meter readings
• /nozzle-reconciliationsElectronic versus manual meter comparison
• /stock-sheetsStock sheet lines, nozzle lines, finance lines, review and export
• /exceptionsVariances and other items that need attention

Pricing

Price books and governed price changes.

• /pricingChange requests, approval, scheduling, activation, rollback and verification
• /stations/{stationId}/pricesCurrent, upcoming and historical prices per station

Team

Staff members, invitations and availability.

• /staff/membersStaff in the workspace and their roles
• /staff/invitesEmail invitations, resend and revoke
• /staff/availabilityWhen staff can work

Maintenance

Keeping forecourt equipment in service.

• /maintenance/plansPlanned maintenance schedules
• /maintenance/work-ordersWork orders from request to completion
• /maintenance/recordsCompleted maintenance history

Reporting and compliance

Dashboards, reports and compliance records.

• /dashboardOperational summary figures
• /reportsOperations reporting
• /complianceSafety and compliance records

System

Health and app version checks.

• /healthLiveness check, no authentication required
• /appApp version information for update prompts