Authentication

Every Revolution API call — REST, SignalR, MQTT — needs a bearer token tied to a real user in a real tenant. We use OAuth 2.0 with PKCE; there are no API keys.

Tip

If you only need to call the API from your own backend, use the client-credentials flow at the bottom of this page. The PKCE flow below is for apps acting on behalf of an end user.

Quickstart

1. Register your client in the Revolution admin → API clients.

2. Send the user to the authorization endpoint with a PKCE challenge.

3. Exchange the returned code for an access token.

4. Send the token as a bearer header on every subsequent request.

Token exchange

Once the user has authorized, your callback receives ?code=…&state=…. Exchange the code:

curl

curl -X POST https://api.revolution.io/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "code": "<auth-code>",
    "code_verifier": "<pkce-verifier>",
    "client_id": "<your-client-id>",
    "redirect_uri": "https://your.app/callback"
  }'

Python

import httpx

resp = httpx.post(
    "https://api.revolution.io/v1/auth/token",
    json={
        "code": auth_code,
        "code_verifier": pkce_verifier,
        "client_id": CLIENT_ID,
        "redirect_uri": "https://your.app/callback",
    },
)
resp.raise_for_status()
token = resp.json()["access_token"]

JavaScript

const resp = await fetch("https://api.revolution.io/v1/auth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    code: authCode,
    code_verifier: pkceVerifier,
    client_id: CLIENT_ID,
    redirect_uri: "https://your.app/callback",
  }),
});
const { access_token } = await resp.json();

Calling the API

Pass the token in the Authorization header.

curl

curl https://api.revolution.io/v1/devices \
  -H "Authorization: Bearer $TOKEN"

Python

import httpx

client = httpx.Client(
    base_url="https://api.revolution.io/v1",
    headers={"Authorization": f"Bearer {token}"},
)
devices = client.get("/devices").json()

JavaScript

const devices = await fetch("https://api.revolution.io/v1/devices", {
  headers: { Authorization: `Bearer ${token}` },
}).then((r) => r.json());

Token lifetime

Access tokens are short-lived (1 hour by default). Use the refresh_token returned by the exchange to mint a new one without re-prompting the user.

Don't ship tokens to the browser

Bearer tokens grant full access to a tenant for their lifetime. Store them server-side, in a session cookie scoped to your origin, or in sessionStorage — never localStorage.

Client-credentials flow

For machine-to-machine integrations (CI bots, scheduled jobs, internal services), use the client-credentials flow instead of PKCE.

curl -X POST https://api.revolution.io/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<service-client-id>",
    "client_secret": "<service-client-secret>"
  }'

The returned token is scoped to the service account’s role in your tenant. Create a service account with least-privilege roles in Revolution admin → Service accounts.