Read the Ruba API Contract

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 on your server and pass its customer access token to the portal API.

Organization request

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.

Follow the request cycle

Every endpoint page is arranged in the same working order:

Read the intent

Confirm that the operation owns the state transition or lookup your integration needs.

Check the access boundary

Match the credential type and required scopes before constructing the request.

Build the request

Select the environment, fill path and query values, and supply the documented body when one is required.

Inspect every documented result

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.

curl "https://api.getruba.com/v1/products/?page=1&limit=10" \
  -H "Authorization: Bearer $RUBA_OAT" \
  -H "Accept: application/json"

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

import { Ruba } from "@getruba/sdk";

const ruba = new Ruba({
  accessToken: process.env.RUBA_ACCESS_TOKEN!,
  server: "sandbox",
});

import os
from ruba import Ruba

client = Ruba(
    access_token=os.environ["RUBA_ACCESS_TOKEN"],
    server="sandbox",
)

import rubago "github.com/rubadot/ruba-go"

client := rubago.New(
  rubago.WithServer("sandbox"),
  rubago.WithSecurity(os.Getenv("RUBA_ACCESS_TOKEN")),
)

$client = Ruba\Ruba::builder()
    ->setServer('sandbox')
    ->setSecurity(getenv('RUBA_ACCESS_TOKEN'))
    ->build();

Enter through the transaction journey

Create a sale

Catalog, checkout sessions, buy links, discounts, and checkout fields.

Manage recurring revenue

Subscriptions, usage events, meters, balances, and seat assignments.

Model customer access

Customer records, members, benefits, licenses, and files.

React to state changes

Webhook payloads for customer, billing, fulfillment, and organization events.

Read This First

Create a Sale

Collect and Reconcile

Manage Recurring Revenue

Model Customer Access

Power the Customer Portal

Configure the Platform

React to State Changes

Read the Ruba API Contract

Choose the authority boundary first

Pick the environment deliberately

Follow the request cycle

Make the first read

Walk a collection without losing your place

Budget requests and retries

Start from an official SDK

Enter through the transaction journey

Create a sale

Manage recurring revenue

Model customer access

React to state changes

​Choose the authority boundary first

​Pick the environment deliberately

​Follow the request cycle

​Make the first read

​Walk a collection without losing your place

​Budget requests and retries

​Start from an official SDK

​Enter through the transaction journey

Create a sale

Manage recurring revenue

Model customer access

React to state changes

Choose the authority boundary first

Pick the environment deliberately

Follow the request cycle

Make the first read

Walk a collection without losing your place

Budget requests and retries

Start from an official SDK

Enter through the transaction journey