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 public specification lives in the rg-specifications repository.

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. Credentials are revocable individually by identifier, effective on the next request. 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 whole API. Tenant scoping means every request is confined to the caller's tenant: a resource belonging to another tenant is indistinguishable from one that doesn't exist, and cross-tenant access returns "not found" rather than "forbidden", so identifiers can't be enumerated. Pagination means list endpoints return results in bounded pages rather than unbounded dumps, so a caller iterates deterministically regardless of fleet size. Neither invariant is optional or per-endpoint — they are properties of the API surface as a whole, which is what lets integrations rely on consistent isolation and consistent iteration 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 public specification

This page is conceptual; the authoritative, versioned API specification is published separately at the rg-specifications repository: github.com/remotegenius/rg-specifications. Consult it for exact resource paths, fields, and response shapes. Keeping the specification in its own repository lets integrators track API changes directly against a single source of truth, while this documentation explains the model those endpoints implement.