Control-plane API reference

The control plane is the platform API behind the RestWard dashboard and the restward CLI. It manages your organization: database connections, generated APIs, endpoints, API keys, roles, members, billing, domains and single sign-on.

It is not the API RestWard generates for your database. That data plane lives on your own API URL and is authenticated with API keys; see API keys & tenant API auth.

• Base URL: https://api.restward.tech/api/v1
• Format: JSON. Enums are strings, ids are GUIDs, timestamps are ISO 8601.
• Machine-readable spec: restward_control-plane.json (OpenAPI 3.1). Load it into Postman, Insomnia or a code generator. The page below is rendered from the same file.

Authentication

Every operation except sign-in and sign-up needs a JWT bearer token in the Authorization header. Operations that need one list the Bearer authorization in the reference below.

Get a token

Sign in with POST /auth/login. The response holds an access token, a refresh token and the access token's expiry.

curl -X POST https://api.restward.tech/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"..."}'

const res = await fetch("https://api.restward.tech/api/v1/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "you@example.com", password: "..." }),
});
const { accessToken, refreshToken, expiresAt } = await res.json();

res = requests.post(
    "https://api.restward.tech/api/v1/auth/login",
    json={"email": "you@example.com", "password": "..."},
)
tokens = res.json()  # accessToken, refreshToken, expiresAt

var res = await http.PostAsJsonAsync("https://api.restward.tech/api/v1/auth/login",
    new { email = "you@example.com", password = "..." });
var tokens = await res.Content.ReadFromJsonAsync<JsonElement>();

Send the access token on every call:

GET /api/v1/organizations HTTP/1.1
Host: api.restward.tech
Authorization: Bearer <accessToken>

Access tokens are short-lived (15 minutes by default). Before one expires, call POST /auth/refresh with the refresh token (valid for 7 days by default). Refresh tokens rotate: every refresh returns a new refresh token, so store the new one and discard the old. Sign-in also works with passkeys (/auth/passkey/*) and enterprise SSO (/auth/sso/*) where your organization has them enabled; both end in the same token pair.

Organization scoping

A token is scoped to one organization. Its org_id claim names the organization and its role claim your role there. Every route under /organizations/{orgId}/... is checked against the claim: addressing any other organization answers 403. A user who belongs to several organizations lists them with GET /auth/memberships and switches with POST /auth/switch-org, which returns a new token pair scoped to the chosen organization.

Inside an organization, what you may do depends on your role (Administrator, Contributor, Auditor, Reader). Operations that need a minimum role say so in the reference (x-restward-minimum-role). Read-only roles get 403 on anything that changes data. See RBAC and multi-tenancy.

SystemAdmin operations

A few operations are for platform operators only (the SystemAdmin role): tenants, platform settings, compute resources, organization deletion and offboarding, direct-invoice billing and promoting a user to Administrator. They are marked SystemAdmin only in the reference and carry x-restward-systemadmin: true in the OpenAPI document. Everyone else gets 403. A SystemAdmin token also bypasses the organization check above.

Personal access tokens

Long-lived tokens for scripts and CI are not available on the control plane yet. Until they are, automate with restward login in the CLI or refresh a JWT as described above. This page will document them when they ship.

Errors

Failures return a JSON body with an error message, for example { "error": "Connection not found." }. Some statuses add fields:

Versioning and deprecation policy

• The version is in the path. Everything documented here is v1 (/api/v1). A new major version gets a new prefix (/api/v2) and runs alongside v1.
• Changes within v1 are additive. New endpoints, new optional request fields and new response fields can appear at any time, so clients must ignore unknown response fields. Existing fields are not removed, renamed or retyped, and existing behavior is not tightened, within v1.
• Breaking changes need a new version. That includes removing an endpoint or field, making an optional field required and changing a status code or an error code.
• Deprecation comes with notice. A deprecated endpoint is marked deprecated: true in the OpenAPI document and in the changelog, and answers with a Deprecation header. It keeps working for at least 6 months after the announcement, and a Sunset header gives the removal date once it is set.
• Security fixes are the exception. A change needed to close a vulnerability can ship immediately; it is announced in the changelog.
• The reference cannot drift. This page is generated from the API's own OpenAPI document, and the build fails when the published document differs from the code.

Endpoint reference

The interactive reference lists every operation with its parameters, request bodies and responses. Use the search box to find an operation, or download the OpenAPI document above.