Platform Overview

MAES Platform provides a unified REST API for managing MAES fuel cards. Instead of integrating directly with complex MAES systems, developers can use our simple API to manage fuel cards programmatically.

How It Works

Your Application                MAES Platform                 MAES Portal
      │                                │                                │
      │  client.cards.enable()         │                                │
      │ ─────────────────────────────► │                                │
      │                                │  [Background Job]              │
      │                                │ ─────────────────────────────► │
      │                                │                                │
      │                                │ ◄───────────────────────────── │
      │  { status: "active" }          │                                │
      │ ◄───────────────────────────── │                                │

1. You use the SDK → Simple method calls with your API key
2. We handle MAES → Complex portal automation happens in background
3. You get results → Typed responses + real-time webhook notifications

Key Concepts

Projects

A Project represents a customer account with isolated:

• MAES credentials
• Cards data
• Team members
• API keys
• Webhooks

Your Organization
 └── Project 1 (Company A)
 │    ├── Sandbox Environment
 │    │    ├── Mock Cards
 │    │    └── API Key: sk_sandbox_xxx
 │    └── Production Environment
 │         ├── Real Cards
 │         └── API Key: sk_live_xxx
 │
 └── Project 2 (Company B)
      └── ...

Environments

Each project has two isolated environments:

Environment	Purpose	MAES Integration
Sandbox	Testing & development	Mock data only
Production	Live operations	Real MAES portal

info

Sandbox and Production have completely separate data and API keys.

Cards

Cards represent physical MAES fuel cards with the following lifecycle:

NEW ──────► ACTIVE ◄──────► INACTIVE
  │           │                │
  │   activate()    enable()   │
  │           ◄────────────────┤
  │                  disable() │
  │           ────────────────►│

Status	Description
new	Card exists but not activated
active	Card is activated with fuel enabled
inactive	Card is activated but fuel disabled

API Keys

API keys authenticate your applications:

Type	Prefix	Access
Sandbox	sk_sandbox_*	Sandbox cards
Production	sk_live_*	Production cards

Keys are hashed (SHA-256) and never stored in plain text.

Webhooks

Real-time notifications when events occur:

• card.enabled - Fuel authorizations enabled
• card.disabled - Fuel authorizations disabled
• card.activated - New card activated
• sync.completed - Data sync completed

Security

Credential Storage

• MAES passwords are AES-256 encrypted at rest
• API keys are SHA-256 hashed

Request Security

• Rate limiting per API key
• HTTPS enforced in production
• HMAC-SHA256 webhook signatures

Audit Trail

Every operation is logged with user, action, timestamp, and metadata.