> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getruba.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Read the Ruba API Contract
> Choose an environment and authority boundary, then make, page, and retry requests safely.
export const RubaSocials = () => {
if (typeof document === "undefined") {
return null;
}
const inject = () => {
const footer = document.getElementById("footer");
if (!footer || document.getElementById("ruba-socials")) {
return false;
}
const isDark = document.querySelector("html.dark") || document.querySelector('html[class*="dark"]');
const lineColor = isDark ? "#383838" : "#e8e8ed";
const iconColor = isDark ? "#8e8e93" : "#86868b";
const markColor = isDark ? "#ffffff" : "#08080c";
const hoverColor = "#0071e3";
const div = document.createElement("div");
div.id = "ruba-socials";
div.style.cssText = `display:flex;align-items:center;gap:20px;padding-top:20px;margin-top:20px;border-top:1px solid ${lineColor};width:100%`;
const logo = `Ruba`;
const spacer = ``;
const ig = ``;
const li = ``;
const x = ``;
const github = ``;
div.innerHTML = logo + spacer + ig + li + x + github;
footer.appendChild(div);
return true;
};
if (!document.documentElement.dataset.rubaSocialsObserver) {
document.documentElement.dataset.rubaSocialsObserver = "true";
const observer = new MutationObserver(() => {
if (!document.getElementById("ruba-socials")) {
inject();
}
});
observer.observe(document.body, {
childList: true,
subtree: true
});
}
setTimeout(() => {
if (!inject()) {
const interval = setInterval(() => {
if (inject()) {
clearInterval(interval);
}
}, 500);
setTimeout(() => clearInterval(interval), 10000);
}
}, 300);
return null;
};
The reference is organized around the path money and access take through Ruba. Start with the authority your code should have, then move into the resource group that owns the state you need.
## Choose the authority boundary first
Ruba exposes two API surfaces. They share the same versioned base URL but represent different actors.
| Surface | Credential | What it can see |
| ------------------- | ---------------------------------------- | ---------------------------------------------------------------- |
| Organization API | Organization Access Token or OAuth token | Resources permitted by the token scopes across the organization. |
| Customer Portal API | Customer access token | Data and actions belonging to the authenticated customer. |
Use an organization credential only from trusted server-side code. When browser code needs customer-owned billing data, create a [customer session](/api-reference/customer-portal/sessions/create) on your server and pass its customer access token to the portal API.
```http Organization request theme={"system"}
Authorization: Bearer ruba_oat_xxxxxxxxxxxxxxxxx
```
Never place an Organization Access Token in browser code, public source,
analytics payloads, or application logs.
## Pick the environment deliberately
| Mode | Root | Use it for |
| ---------- | ------------------------------------ | -------------------------------------------- |
| Sandbox | `https://sandbox-api.getruba.com/v1` | Integration builds and test data. |
| Production | `https://api.getruba.com/v1` | Live organizations, customers, and payments. |
Sandbox and production do not share organizations, records, or credentials. Create a token in each environment and keep the variables separate. See [Build Safely in the Sandbox](/integrate/sandbox).
## Follow the request cycle
Every endpoint page is arranged in the same working order:
Confirm that the operation owns the state transition or lookup your integration needs.
Match the credential type and required scopes before constructing the request.
Select the environment, fill path and query values, and supply the documented body when one is required.
Use the success schema for normal processing and handle the listed error responses explicitly.
The **Try it** workspace keeps this sequence together. It does not change the endpoint contract; it gives you an interactive way to assemble the same request shown in the code examples.
## Make the first read
The following request lists catalog items without changing organization state.
```bash Production theme={"system"}
curl "https://api.getruba.com/v1/products/?page=1&limit=10" \
-H "Authorization: Bearer $RUBA_OAT" \
-H "Accept: application/json"
```
```bash Sandbox theme={"system"}
curl "https://sandbox-api.getruba.com/v1/products/?page=1&limit=10" \
-H "Authorization: Bearer $RUBA_OAT_SANDBOX" \
-H "Accept: application/json"
```
## Walk a collection without losing your place
Collection operations accept `page` and `limit`.
| Input | Default | Maximum | Meaning |
| ------- | ------- | ------- | ----------------------------------------- |
| `page` | `1` | — | One-based page to read. |
| `limit` | `10` | `100` | Maximum records returned by that request. |
The response includes:
| Field | Meaning |
| ------------- | ---------------------------------------------- |
| `total_count` | Records matching the request across all pages. |
| `max_page` | Last available page for the selected limit. |
Continue until the requested page reaches `max_page`. Official SDK pagination helpers can perform this iteration for you.
## Budget requests and retries
Rate limits are applied per organization, customer, or OAuth client:
* Production: **500 requests per minute**.
* Sandbox: **100 requests per minute**.
* Unauthenticated license-key validation, activation, and deactivation: **3 requests per second** in either environment.
When the budget is exhausted, Ruba returns `429 Too Many Requests`. Wait for the number of seconds supplied in `Retry-After` before sending the next attempt.
## Start from an official SDK
```ts TypeScript theme={"system"}
import { Ruba } from "@getruba/sdk";
const ruba = new Ruba({
accessToken: process.env.RUBA_ACCESS_TOKEN!,
server: "sandbox",
});
```
```py Python theme={"system"}
import os
from ruba import Ruba
client = Ruba(
access_token=os.environ["RUBA_ACCESS_TOKEN"],
server="sandbox",
)
```
```go Go theme={"system"}
import rubago "github.com/rubadot/ruba-go"
client := rubago.New(
rubago.WithServer("sandbox"),
rubago.WithSecurity(os.Getenv("RUBA_ACCESS_TOKEN")),
)
```
```php PHP theme={"system"}
$client = Ruba\Ruba::builder()
->setServer('sandbox')
->setSecurity(getenv('RUBA_ACCESS_TOKEN'))
->build();
```
## Enter through the transaction journey
Catalog, checkout sessions, buy links, discounts, and checkout fields.
Subscriptions, usage events, meters, balances, and seat assignments.
Customer records, members, benefits, licenses, and files.
Webhook payloads for customer, billing, fulfillment, and organization events.