| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Lines of code | 3648 |
| Technical Name |
api_gateway |
| License | LGPL-3 |
| Website | mailto:piyush23321@gmail.com |
| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Lines of code | 3648 |
| Technical Name |
api_gateway |
| License | LGPL-3 |
| Website | mailto:piyush23321@gmail.com |
Veloxio · For Odoo 19
API Gateway Pro
Transform your Odoo into a secure, production-ready REST API server. No Redis, no middleware, no extra infrastructure - powered entirely by native Odoo and PostgreSQL.
REST API
OAuth2 JWT
Webhooks
Rate Limiting
OpenAPI Docs
Live Dashboard
IP Whitelist
Odoo 19 Compatible
⚡ Sub-millisecond Auth
🔒 Dual Authentication
📊 9 Live Charts
🪝 Async Webhooks
By the numbers
Everything in one module
A complete API infrastructure layer - from authentication to analytics - built natively inside Odoo.
9
Live Charts
15+
KPI Metrics
5
HTTP Methods
4
OAuth2 Scopes
0
Extra Servers
∞
Odoo Models
5
Auto Cron Jobs
3
Webhook Triggers
01 · Analytics
Real-Time Analytics Dashboard
A fully custom OWL component with 9 live ApexCharts, 15+ KPIs, WebSocket push, animated counters, sound alerts, and a live fault feed - all inside Odoo.
📈
Traffic vs Errors - Area Chart
Smooth area chart showing total requests, errors, and rate-limited calls
over 24h, 30 days, or 1 year. Hourly buckets for short range,
daily buckets for long range.
🍩
Top Endpoints - Donut Chart
Top 5 most-hit API endpoints by request volume. Hover to see
exact counts. Total shown in the donut center.
🛡️
System Health - Radial Gauge
0–100 health score calculated from error rate and latency.
Color changes: green (healthy), amber (degraded), red (critical).
⏱️
Slowest Endpoints - Horizontal Bar
Ranks your API endpoints by average response time in milliseconds.
Instantly spot performance bottlenecks.
🌐
Top IP Addresses - Bar Chart
Real-time breakdown of which IP addresses are generating the
most traffic. Useful for detecting abuse or heavy clients.
📡
Latency Histogram - Column Chart
Bucketed latency distribution: <10ms, 10–50ms, 50–100ms,
100–500ms, >500ms. See your overall speed profile at a glance.
🔀
HTTP Method Breakdown - Bar Chart
Colorful breakdown of GET, POST, PUT, PATCH, DELETE request
counts. Know exactly how your API is being used.
📤
Webhook Queue - Radial Chart
Pending vs failed async webhook jobs shown as a radial bar.
Instantly see if your outbound queue is healthy.
✅
Status Distribution - Bar Chart
2xx Success, 4xx Client Errors, 5xx Server Errors, 429 Rate Limited -
four-column breakdown of all response outcomes.
Primary KPI Cards
Animated counter cards at the top of the dashboard. All values update smoothly with cubic easing on every data refresh.
Live Push & Controls
- ✓ WebSocket mode - Odoo bus pushes telemetry instantly. No polling needed. Heartbeat RPS counter increments in real time.
- ✓ Polling fallback - Choose 5s, 10s, 30s, or 60s intervals if WebSocket is unavailable.
- ✓ Manual mode - Pause all updates and refresh on demand.
- ✓ Sound alerts - Web Audio API plays a tone on 5xx errors. Toggle on/off from the header.
- ✓ Toast notifications - Slide-in alerts when error rate exceeds 10% or a 5xx is detected.
- ✓ Light / Dark / Auto theme - All 9 charts rerender in the selected theme instantly.
- ✓ Time filters - 24H, 30D, 1Y range selector updates all charts simultaneously.
- ✓ User & status filter - Drill down by specific API key user or status code class.
Live Fault Feed
Bottom section of the dashboard - a live updating table of all failed requests (4xx/5xx). Click Inspect on any row to open the full log record in a popup. Export to CSV with one click.
02 · Core Engine
Universal REST API Engine
One endpoint pattern works for every Odoo model instantly - no custom routes, no extra code, no scaffolding required.
Endpoint Pattern
# List records
GET /api/v1/res.partner
GET /api/v1/sale.order
GET /api/v1/product.template
# Single record
GET /api/v1/res.partner/42
# Create
POST /api/v1/res.partner
Body: {"name": "Acme Corp", "email": "a@acme.com"}
# Update
PUT /api/v1/res.partner/42
Body: {"phone": "+1 555 0100"}
# Delete
DELETE /api/v1/res.partner/42
Smart Query Parameters
# Filter with Odoo domain syntax
?domain=[('is_company','=',True)]
# Select specific fields
?fields=name,email,phone
# Pagination
?limit=25&offset=50
# Ordering
?order=name%20asc
Complete Endpoint Reference
| Method | Endpoint | Action | Notes |
|---|---|---|---|
| GET | /api/v1/<model> | search_read() | Supports domain, fields, limit, offset, order |
| GET | /api/v1/<model>/<id> | search_read() | Returns single record by ID |
| POST | /api/v1/<model> | create() | JSON body → new record. Returns created ID. |
| PUT | /api/v1/<model>/<id> | write() | Full or partial update |
| PATCH | /api/v1/<model>/<id> | write() | Alias for PUT |
| DELETE | /api/v1/<model>/<id> | unlink() | Permanently deletes the record |
| GET | /api/v1/ping | Health check | Returns pong + user + timestamp |
Native ACL Enforcement: Every request runs under the authenticated user's Odoo session.
All native Record Rules (ir.rule) and Access Control Lists are automatically enforced.
Violations return 403 Forbidden. Missing records return 404 Not Found.
03 · Authentication
OAuth2 Authentication - JWT
Full OAuth2 Client Credentials flow with signed JWT tokens, scope-based access control, token revocation, and automatic cleanup. Built for machine-to-machine (M2M) integrations.
Authentication Flow
1
Create OAuth2 Client
In API Gateway → OAuth2 Clients, create a client. Auto-generated Client ID (
gw_xxxxxxxxxxxx) and 32-char secret shown once.2
Request JWT Token
POST client credentials to
/api/oauth/token with grant_type=client_credentials.3
Receive Signed JWT
Server validates credentials, checks IP whitelist, negotiates scopes, and returns HMAC-SHA256 signed JWT with JTI, sub, exp, scopes.
4
Use as Bearer Token
Attach JWT as
Authorization: Bearer <token> on every API call. Scopes enforced per HTTP method.
read
Read Scope
Allows GET requests only. Safe for read-only integrations like reporting dashboards or sync jobs.
write
Write Scope
Allows POST, PUT, PATCH requests. For integrations that need to create or update records.
delete
Delete Scope
Allows DELETE requests. Intentionally separate so you can grant write without delete.
admin
Admin Scope
Grants all methods plus access to admin endpoints like
/api/oauth/clients.Token Request & Response
# Step 1 - Get a JWT token
POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=gw_a1b2c3d4e5f6
&client_secret=your_32_char_secret
&scope=read write
# Response 200 OK
{
"access_token": "eyJhbGciOiJIUzI1NiJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "read write"
}
# Step 2 - Use the token
GET /api/v1/res.partner
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
04 · Authentication
Odoo API Key Authentication
Built on top of Odoo's native res.users.apikeys infrastructure.
Zero extra setup - keys already exist in every Odoo instance.
- ✓ Native integration - uses the same keys Odoo already generates in user preferences. No new key storage.
- ✓ RAM-cached validation - token lookup happens entirely in-memory via
@tools.ormcache. Zero database hits per request during validation. - ✓ 600,000 PBKDF2-SHA512 rounds - constant-time passlib verification prevents timing attacks.
- ✓ API Profiles - attach a custom profile (rate limit, IP whitelist) to any Odoo user. All their API keys inherit the profile's rules automatically.
- ✓ Key expiration - optional expiry date per key. Expired keys return 401.
- ✓ Cache invalidation - profile changes flush the registry cache instantly so policy updates take effect immediately.
# Any API request with an Odoo key
GET /api/v1/res.partner
Authorization: Bearer 1$your_odoo_api_key_here
05 · Security
Atomic Rate Limiting - Zero Redis
Enterprise-grade rate limiting powered purely by a single atomic PostgreSQL UPSERT. No Redis, no Celery, no distributed lock managers needed.
How it works
- ✓ Atomic UPSERT - single
INSERT ... ON CONFLICT DO UPDATESQL statement. Increments the counter and returns the new value in one round-trip. - ✓ Multi-worker safe - works across all Odoo worker processes without any inter-process communication.
- ✓ Three time windows - per-minute, per-hour, per-day. Each tracked independently.
- ✓ Per-user limits - API Profiles set individual rate limits per user or OAuth2 client.
- ✓ Global fallback - a global limit applies to any user without a custom profile.
- ✓ 429 response - rate-limited requests return
HTTP 429 Too Many Requestswith a JSON error body. - ✓ Live throttle view - see active rate limit windows per user in real time via API Gateway → Active Throttles.
-- The atomic UPSERT (simplified)
INSERT INTO api_gateway_throttle
(user_id, window_type, window_start, count)
VALUES (%s, %s, %s, 1)
ON CONFLICT ON CONSTRAINT ...
DO UPDATE SET
count = api_gateway_throttle.count + 1
RETURNING count;
06 · Security
IP Whitelisting
Restrict API access to trusted IP addresses at both the profile level and per OAuth2 client. Requests from unlisted IPs are rejected immediately.
🧑💼
Profile-Level Whitelist (API Keys)
Set allowed IPs or CIDR ranges directly on the API Profile linked to a user.
All API key requests from that user are checked against this list.
Leave blank to allow all IPs.
- ✓ Per-user configuration
- ✓ Supports multiple IPs (newline-separated)
- ✓ 403 returned for non-whitelisted IPs
🤖
Client-Level Whitelist (OAuth2)
Each OAuth2 client has its own IP whitelist. Enforced both at token
issuance (
/api/oauth/token) and on every API call using that token.
- ✓ Per-client configuration
- ✓ Checked at token request AND token use
- ✓ Combines with scope enforcement
07 · Integrations
Outbound Webhooks
Push real-time events from any Odoo model to any external URL - automatically, asynchronously, and reliably. No external queue broker required.
Configuration
- ✓ Any Odoo model - bind a webhook to res.partner, sale.order, stock.picking, or any custom model.
- ✓ Three triggers - fire on
create,write, orunlink. - ✓ Custom HTTP headers - add any headers directly from the UI (Authorization, X-API-Key, X-Signature, etc.).
- ✓ Async queue - webhook jobs are queued immediately without blocking the user's browser or the ORM transaction.
- ✓ Cron processing - background cron runs every minute, processes up to 50 pending jobs, with a 10-second timeout per call.
- ✓ Retry with backoff - failed jobs are retried automatically. Error messages stored for debugging.
- ✓ Auto-vacuum - old processed jobs cleaned up after 30 days automatically.
Payload Structure
# Example: res.partner create event
{
"action": "create",
"model": "res.partner",
"record": {
"id": 147,
"name": "Acme Corp",
"email": "hello@acme.com",
"create_date": "2025-03-14T10:30:00"
}
}
# For unlink - only ID is sent
{
"action": "unlink",
"model": "res.partner",
"record": { "id": 147 }
}
08 · Developer Portal
Interactive API Documentation
A beautiful Scalar UI portal embedded directly in Odoo at /api/docs -
backed by a dynamic OpenAPI 3.0 spec. No external hosting, no Swagger UI.
🎮
Try-It-Out Interface
Execute live API calls directly from the documentation page.
Enter your Bearer token once, test any endpoint interactively.
See real request/response pairs.
📄
Dynamic OpenAPI 3.0
GET /api/openapi.json returns a fully generated OpenAPI
3.0 spec with all endpoints, parameters, request bodies, and security
schemes. CORS enabled for external tools.
📋
Copy-Paste curl Commands
Every endpoint shows a ready-to-use curl command with your actual
token and parameters filled in. Import into Postman, Insomnia,
or any API client in seconds.
09 · Observability
Traffic Logs & Telemetry
Every API request can be logged with configurable detail levels. Bearer tokens are auto-redacted. Full payload capture available for debugging.
Three Log Levels
Errors Only
Logs only failed requests (status ≥ 400). Lowest storage footprint. Recommended for production.
Metadata
Logs all requests with headers, IPs, status codes, and latency. No request/response bodies.
Full Payloads
Logs everything including UTF-8 decoded request and response bodies. For deep debugging.
- ✓ Auto-redaction - Bearer tokens in Authorization headers stored as
Bearer **********. Secrets never leak into logs. - ✓ Error traceback - full Python traceback stored on 5xx errors for debugging.
- ✓ Auto-vacuum - logs older than the configured retention period (default 30 days) deleted automatically by cron.
- ✓ Group by - group log records by date, user, status code, or endpoint.
- ✓ Smart buttons - from an API Profile, click through directly to that user's traffic logs.
10 · UI Design
Light / Dark / Auto Theme
The dashboard ships with a fully themeable design system. Three modes, all 9 charts rerender in real time, settings persist per browser.
🌙
Dark Theme
Deep navy background (#0b0f19) with subtle neon glow on KPI values. All 9 charts switch to ApexCharts dark mode. Cards with glassmorphism borders.
☀️
Light Theme
Clean white cards on light slate background. High contrast text. All 9 charts switch to light mode. Professional look for daytime use.
💻
Auto Theme
Follows the operating system's
prefers-color-scheme media query. Switches automatically when OS theme changes. No manual toggle needed.
11 · Configuration
Global Settings
All global policies configured in one place under Settings → API Gateway. No file editing required.
| Setting | Default | Description |
|---|---|---|
| Default GET Limit | 80 | Max records returned if client doesn't specify |
| Global Rate Limit | 60 | Fallback requests per window for users without a profile |
| Rate Window | minute | minute / hour / day |
| Log Level | errors | errors / metadata / payloads |
| Log Retention | 30 days | Days before logs are auto-deleted |
| JWT Secret | auto-gen | HMAC-SHA256 signing key for OAuth2 tokens |
12 · Why choose us
API Gateway Pro vs Alternatives
See how API Gateway Pro compares to typical approaches for exposing Odoo data to external systems.
| Feature | API Gateway Pro ⚡ | Custom Odoo Routes | Odoo Default XML-RPC |
|---|---|---|---|
| Works on any model instantly | ✓ Yes | ✗ Manual per-model | ~ Limited |
| OAuth2 JWT Authentication | ✓ Yes | ✗ Build yourself | ✗ No |
| Rate Limiting (no Redis) | ✓ Yes | ✗ Build yourself | ✗ No |
| IP Whitelisting | ✓ Yes | ✗ Build yourself | ✗ No |
| Outbound Webhooks | ✓ Yes | ✗ Build yourself | ✗ No |
| Real-Time Analytics Dashboard | ✓ Yes | ✗ No | ✗ No |
| Interactive API Docs (OpenAPI) | ✓ Yes | ✗ No | ✗ No |
| RESTful JSON responses | ✓ Yes | ~ Manual | ✗ XML-RPC only |
| Native ACL/Record Rule enforcement | ✓ Yes | ~ Manual | ✓ Yes |
| Zero extra infrastructure | ✓ Yes | ✓ Yes | ✓ Yes |
13 · Maintenance
Automatic Maintenance Crons
Five background cron jobs keep your API Gateway clean and efficient with zero manual intervention.
🗑️
Log Auto-Vacuum
Deletes traffic logs older than the configured retention period. Runs every 30 days. Keeps your database lean.
📤
Webhook Processor
Processes up to 50 pending webhook jobs per run. Runs every minute. 10-second timeout per call. Stores errors for debugging.
🧹
Webhook Job Vacuum
Cleans up old completed and failed webhook jobs based on retention policy. Runs every 30 days.
🔑
OAuth Secret Hider
Clears the one-time client secret display field after 24 hours. Runs every 6 hours. Prevents accidental secret exposure.
🪣
Token Vacuum
Permanently deletes expired OAuth2 tokens older than 7 days. Runs daily. Keeps the token table clean and fast.
14 · Navigation
Module Menu Structure
All features accessible from a single top-level menu: API Gateway.
API Gateway
├── Dashboard (real-time command center)
│
├── Traffic Logs (all request logs)
│
└── Configuration
├── Settings (global policies)
├── API Profiles (user-level rules)
├── OAuth2 Clients (M2M app credentials)
├── OAuth2 Tokens (audit trail)
├── Active Throttles (live rate limit view)
└── Webhooks
├── Configuration (webhook setup)
└── Webhook Queue (async job status)
Requirements
Compatibility
🟣
Odoo 19
Community & Enterprise
🐘
PostgreSQL 14+
Required for atomic UPSERT
🐍
Python 3.10+
Bundled with Odoo 19
📦
Dependencies
base, web, bus - all native
No external packages required. The module uses only Python's
built-in
hmac, hashlib, json, and base64
modules for JWT encoding. No PyJWT, no Redis, no Celery.
⚡ Veloxio
API Gateway Pro · v19.0.3.1.0 · LGPL-3
Support: piyush23321@gmail.com
For Odoo 19 · No Redis · No Middleware · Native PostgreSQL
Please log in to comment on this module