API access
Use the SDK for supported app behavior. It owns identity proof, session handling, request scheduling, and retries. Do not add direct customer API calls around it to work around missing configuration.
| Surface | Caller | Authentication |
|---|---|---|
/v1/* |
App SDK or supported trusted server integration | App API key; customer/session proof as required |
/dashboard/*, /admin/* |
One Admin | Platform user session and workspace membership |
/agent/*, /mcp |
One Agent client | Scoped Agent token |
/webhooks/* |
Supported external provider | Provider signature or configured verification |
The API key resolves the app, project, workspace, and environment. A client-supplied app ID is not permission to access another app.
Public and secret keys
Section titled “Public and secret keys”Public keys can be embedded in a client for permitted operations. Secret keys belong only on trusted servers. A public key is not a replacement for customer session proof. Agent tokens are a separate credential with their own scopes and allowed-app restrictions.
Errors and retries
Section titled “Errors and retries”Treat validation and permission errors as problems to correct, not requests to retry indefinitely. Honor rate limits and Retry-After. Let the SDK handle its normal retry policy. Do not turn missing configuration into a silent success or invented default.
Agent integration
Section titled “Agent integration”Use One Agent for bounded configuration, reports, and diagnostics. Changes use a preview/action plan followed by explicit apply. A saved plan’s existence is not approval to execute it.
Start with the iOS SDK or web and desktop SDK for customer-facing features. Use the documented Agent tools for administration. Dashboard routes are used by One Admin and are not a public integration contract.
Base URL and headers
Section titled “Base URL and headers”The API origin is https://one.rambax.com. SDK builds use this origin directly; SDK configuration does not accept an apiUrl override.
| Header | Purpose |
|---|---|
x-one-api-key |
App public or secret key; resolves the physical Test or Live app |
x-one-platform |
ios, android, web, windows, or macos; must be compatible with the app |
x-one-customer-id |
SDK-managed app customer identifier |
x-one-customer-token |
Proof for that customer; an ID alone is insufficient |
Authorization: Bearer … |
Customer session where required, or a scoped Agent token on Agent/MCP routes |
Content-Type: application/json |
JSON request bodies |
x-one-sdk-version |
SDK compatibility and diagnostics |
Do not expose secret app keys or Agent tokens in browser bundles, iOS resources, URLs, or logs. Customer account operations also enforce their session and recent-authentication requirements; having an app key does not grant access to another customer’s account.
A read-only Agent request looks like this. The token is supplied through the shell environment:
curl --fail-with-body https://one.rambax.com/agent/context \ -H "Authorization: Bearer $ONE_AGENT_TOKEN"Error envelope
Section titled “Error envelope”The shared API error handler returns a JSON object such as:
{ "error": "validation_error", "message": "The request could not be validated", "requestId": "request identifier"}error is a machine-readable code. message describes the failure. requestId, when present, helps trace it. Validation responses may include field details. Some endpoint-specific failures return their own documented error fields.
| Status | Meaning | Caller action |
|---|---|---|
| 400 | Invalid input or incompatible state | Correct the input; do not repeatedly retry |
| 401 | Missing, expired, or invalid credentials | Let the SDK restore the session or sign in again |
| 403 | Scope, app restriction, or role denies access | Use the correct authorized account/token |
| 404 | Resource missing or outside the caller’s scope | Check the exact app and record |
| 409 | Conflict or stale action plan | Read current state and create a new reviewed plan |
| 413 | Request exceeds a size bound | Reduce the payload; use documented batching |
| 429 | Rate limited | Honor Retry-After |
| 500–503 | Server or dependency failure | Use bounded retries only where the operation is safe to repeat |
Pagination, time, and retries
Section titled “Pagination, time, and retries”Pagination is endpoint-specific: lists may use a cursor or limit with offset. Follow the endpoint contract rather than assuming one pagination format. New Admin configuration reads cap results at 100 and return hasMore; narrow with an exact ID when needed. Do not mistake a bounded page for the entire dataset.
Send timestamps as ISO 8601 strings. Dashboard date-only report filters use UTC day boundaries. A report’s coverage or availability result is part of its meaning: unavailable data is not zero activity.
The SDK batches up to 25 events and limits request concurrency to four. Entitlement reads normally share a 60-second freshness window. Do not add per-screen refresh loops or extra connectivity probes around the SDK. Retrying a purchase, provider action, or Agent apply is different from retrying a read: inspect the existing operation after an uncertain response instead of blindly creating another operation.
Full reference
Section titled “Full reference”Browse the endpoint reference, all MCP tools, and Admin action contracts. Request JSON Schemas and endpoint contracts are downloadable from the reference index. The reference documents the current customer and Agent surfaces; private dashboard routes are not promised as a stable external API.