Skip to content

API overview

The RG API is a resource-oriented HTTP interface over the platform's core entities, governed by the same auth and isolation model as the rest of the platform. A cloud session is exchanged for a short-lived, cluster-scoped credential; every request is scoped to the caller's tenant; and list results are paginated. This page describes the conceptual surface — the interactive, versioned API reference is published at cloud.remotegeni.us/docs.

Authentication model

Authentication mirrors the platform's layer separation. A user first holds a cloud session obtained by signing in to the cloud. To act on a specific cluster, that session is exchanged for a short-lived, cluster-scoped credential valid only on that cluster and only until it expires; the caller then addresses the cluster's API directly with it, and the cloud is not in the request path. Non-interactive callers use machine credentials whose secret is revealed exactly once at creation and stored only as an irreversible hash — there is no way to retrieve it later. User sessions and machine credentials are revocable individually by identifier, effective on the next request; short-lived cluster-scoped credentials are instead bounded by their expiry. Devices never use this API; they authenticate only to their own cluster.

Resource orientation

The API is organized around a small set of resource types that mirror the platform's entities: organizations, clusters, bridges, devices, roles, and audit events. Organizations contain clusters; clusters home devices and bridges; roles define authority under the two-tier RBAC model; audit events record consequential actions. Bridges and devices are distinct resource types with separate lifecycles, matching the data model — a bridge's form factor is one of exactly two values (agent or appliance), and a device's attachment state is one of exactly three (never_attached, attached, or detached). Callers navigate these resources through conventional collection and item paths, with the cluster-scoped credential determining which cluster's resources are reachable.

Invariants: pagination and tenant scoping

Two invariants hold across the API. Tenant scoping means every request is confined to the caller's tenant: a resource belonging to another tenant is returned as "not found" rather than as "forbidden", so identifiers can't be enumerated — while a credential presented against an organization it is not scoped to is refused as "forbidden". Pagination means list endpoints return results in bounded pages rather than unbounded dumps, so a caller iterates deterministically regardless of fleet size; most collections page by offset (page and pageSize), while high-volume collections such as audit events use keyset pagination (cursor and limit). Tenant scoping is a property of every data-access path rather than a per-endpoint opt-in, which is what lets integrations rely on consistent isolation everywhere.

Illustrative request shapes

The two shapes below are illustrative only, using documentation hosts and fake identifiers. They convey structure, not a literal endpoint reference — consult the published specification for exact paths and fields.

Exchange a cloud session for a cluster-scoped credential:

POST /v1/clusters/clu_9f8e7d/credentials HTTP/1.1
Host: api.example.com
Authorization: Bearer <cloud-session-credential>
Accept: application/json

List a cluster's devices, one page at a time:

GET /v1/clusters/clu_9f8e7d/devices?page=1 HTTP/1.1
Host: cluster.example.com
Authorization: Bearer <cluster-scoped-credential>
Accept: application/json

The API reference

This page is conceptual; the authoritative, versioned API reference is published at cloud.remotegeni.us/docs. Consult it for exact resource paths, fields, and response shapes. Generating the reference from the running API gives integrators a single source of truth to track changes against, while this documentation explains the model those endpoints implement.