API Reference and Rate Limiting
Authentication Methods
ORBEXA supports three authentication methods:API Key Authentication
Used for MCP tool calls and API access:OAuth Authentication
Used for platform integrations such as Shopify, following the standard OAuth 2.0 flow.Plugin Header Authentication
Used for WordPress plugin integration, requiring the following headers:X-Plugin-Platform— Platform identifierX-Plugin-Version— Plugin version number
Complete Endpoint Catalog
UCP Endpoints
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/.well-known/ucp | GET | None | UCP discovery document |
/ucp/v1/products | GET | API Key | Product listing (JSON/TSV) |
/ucp/v1/products/:id | GET | API Key | Product details (with variants) |
/ucp/v1/search | GET | API Key | Full-text product search |
/ucp/v1/checkout-sessions | POST | API Key | Create checkout session |
/ucp/v1/manifest | GET | API Key | Merchant capability declaration |
/ucp/acp-feed.json | GET | API Key | ACP-formatted product feed |
ACP Endpoints — JSON-RPC 2.0
| Method | Auth | Description |
|---|---|---|
commerce.search | API Key | Product search |
commerce.product | API Key | Product details |
commerce.checkout | API Key | Initiate checkout |
commerce.order_status | API Key | Order status query |
commerce.capabilities | API Key | Capability declaration |
ACP Endpoints — REST
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/acp/v1/products | GET | API Key | Product listing |
/acp/v1/checkout | POST | API Key | Checkout operation |
MCP Endpoints
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/mcp/tools | GET | API Key | Tool listing |
/api/mcp/execute | POST | API Key | Execute tool |
/api/mcp/resources | GET | API Key | Resource listing |
/api/mcp/usage | GET | API Key | Usage statistics |
/api/mcp/prompts | GET | API Key | Prompt listing |
Discovery Endpoints
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/.well-known/ucp | GET | None | UCP protocol discovery |
/.well-known/acp | GET | None | ACP protocol discovery |
/.well-known/mcp | GET | None | MCP protocol discovery |
OTR Endpoints
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/otr/verify/:domain | GET | None | Query domain trust score |
/.well-known/otr/verify | GET | None | Standardized trust query endpoint |
Shopify Integration
| Endpoint | Method | Auth | Description |
|---|---|---|---|
| Shopify OAuth Callback | GET | OAuth | Handles Shopify authorization callback |
| Shopify Webhooks | POST | HMAC Signature | Receives Shopify event notifications |
WooCommerce Integration
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/integrations/woocommerce/connect | POST | API Key | Connect store |
/api/integrations/woocommerce/test | POST | API Key | Test connection |
/api/integrations/woocommerce/sync/products | POST | API Key | Sync products |
/api/integrations/woocommerce/sync/orders | POST | API Key | Sync orders |
/api/integrations/woocommerce/sync/inventory | POST | API Key | Sync inventory |
/api/integrations/woocommerce/webhooks/setup | POST | API Key | Register Webhooks |
/api/integrations/woocommerce/webhooks/handle | POST | Signature Verification | Handle Webhook events |
WordPress Integration
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/integrations/wordpress/connect | POST | Header Auth | One-click connection |
/api/integrations/wordpress/status | POST | Header Auth | Query status |
/api/integrations/wordpress/disconnect | POST | Header Auth | Disconnect |
Rate Limiting Policies
Overall Architecture
ORBEXA’s rate limiting system is backed by Redis with in-memory fallback. It uses a token bucket algorithm combined with an exponential backoff strategy:- Token bucket: Each time window allocates a fixed number of tokens; each request consumes one token
- Exponential backoff: After hitting a rate limit, clients should retry with exponentially increasing intervals
Rate Limit Presets by Endpoint Type
| Endpoint Type | Rate Limit | Notes |
|---|---|---|
| UCP endpoints | 100 req/min | Primary access point for AI agents |
| API endpoints | 60 req/min | General API calls |
| Auth endpoints | 10 req/min | Sensitive operations like login/registration |
| Webhook endpoints | 200 req/min | Receiving platform event notifications |
| WordPress plugin | 3 req/min/IP | Plugin connection and status queries |
Platform-Side Rate Limits
ORBEXA also rate-limits calls to upstream platforms to prevent exceeding their API limits:| Platform | Rate Limit | Notes |
|---|---|---|
| Shopify API | 2 req/s | Complies with Shopify API limits |
| WooCommerce API | 5 req/s | Protects merchant servers |
Internal Call Rate Limit Bypass
Internal ORBEXA services (such as self-calls during PDF report generation) bypass rate limiting throughX-OTR-Internal-Key header authentication. This ensures internal processes are not blocked by external rate limiting rules.
Error Handling
Rate Limit Errors
When a request exceeds the rate limit, the API returns HTTP 429 status code:retry_after field indicates the number of seconds the client should wait before retrying.
Authentication Errors
| Status Code | Error | Description |
|---|---|---|
| 401 | unauthorized | Missing or invalid authentication credentials |
| 403 | forbidden | Valid credentials but no access to the requested resource |
General Errors
| Status Code | Error | Description |
|---|---|---|
| 400 | bad_request | Invalid request parameters |
| 404 | not_found | Resource does not exist |
| 500 | internal_error | Internal server error |
Summary
ORBEXA provides a comprehensive API endpoint system covering the three major protocols (UCP/ACP/MCP), OTR trust queries, three platform integrations, and discovery endpoints. The Redis-backed rate limiting system protects endpoints through tiered token bucket policies by endpoint type, while internal calls bypass rate limits through key-based authentication.Back to: ORBEXA Integrated Solution