Skip to content
Developer docs

Authentication and tokens

Call the API and the MCP server with a personal token (qchp_) or a service-account token (qchsa_), narrow it with a binding, and pick the organisation with X-RCH-Org.

Three kinds of credential

Kind

Looks like

Acts as

Get it from

Session

a signed token in the access_token cookie

you, in the browser

signing in through REM Auth

Personal access token

qchp_...

you

Settings > Tokens and secrets or Team > Access tokens > Create token

Service-account token

qchsa_...

a service account (a non-person identity with an owner)

Team > Access tokens > Service accounts

Programs use personal or service-account tokens. Send the token as a bearer token:

curl https://remcloudhub.com/api/me/roles \
  -H "Authorization: Bearer qchp_..."

A token's value is shown once, when it is made; REM CloudHub stores only a hash and a 12-character prefix, which is what lists show. A token can do at most what its owner can do, until it expires or is revoked.

Make a personal token

In the console: Settings > Tokens and secrets > Create token, give it a Name ("deploy script"), an end date, and optionally bind it (below). Copy the value.

From a program that already holds a token:

POST /api/me/access-tokens
Authorization: Bearer qchp_...
Content-Type: application/json

{"name": "ci-deploy", "expires_in_days": 90, "scopes": ["apps", "jobs"]}
{
  "token": "qchp_...shown once...",
  "info": {
    "id": 41, "name": "ci-deploy", "prefix": "qchp_3f9a1c", "username": "asha",
    "scopes": ["apps", "jobs"], "app_id": null, "app_type": "", "allowed_origins": [],
    "require_origin": false, "created_at": "2026-11-18T10:02:11Z",
    "expires_at": "2027-02-16T10:02:11Z", "active": true
  }
}

GET /api/me/access-tokens lists your tokens; DELETE /api/me/access-tokens/{token_id} revokes one. Whether never-expiring tokens are allowed is a platform policy (GET /api/token-options says so, and lists the areas and app types you can bind to).

Narrow a token (binding)

Field

Effect

scopes

API areas the token may call. Empty means every area. Areas: apps, jobs, secrets, files, databases, ai, docs, account, platform, mcp, git, admin

app_id

Only this project's routes, MCP tools and git repository

app_type

The caller must send X-QCH-App-Type with this value; the header alone grants nothing

allowed_origins + require_origin

Browser origins allowed (checked against Origin, else Referer). A server-to-server call without Origin passes unless require_origin is true

expires_in_days / expires_at / never

When it ends

A call outside the binding gets 403 with the reason (wrong area, another app, origin not allowed). An unknown, expired or revoked token gets 401.

Pick the organisation: X-RCH-Org

Lists, permission checks and plan limits answer for one organisation. Send its uid in X-RCH-Org; without it you get your personal organisation. Find the uids with:

GET /api/orgs/mine
Authorization: Bearer qchp_...
{
  "personal_uid": "8c1f2b6e-...",
  "orgs": [
    {"uid": "8c1f2b6e-...", "id": 12, "name": "Asha's organisation", "handle": "calm-river-4821",
     "personal": true, "is_owner": true, "plan": "Free", "plan_code": "free", "trial": null, "frozen": false},
    {"uid": "f04d77a1-...", "id": 31, "name": "Acme Research", "handle": "acme-research",
     "personal": false, "is_owner": false, "plan": "Pro", "plan_code": "pro", "trial": null, "frozen": false}
  ]
}
curl https://remcloudhub.com/api/apps \
  -H "Authorization: Bearer qchp_..." \
  -H "X-RCH-Org: f04d77a1-..."

The response echoes X-RCH-Org. Asking for an organisation you are not in is refused.

Step-up for sensitive actions

Some actions (revealing a service password, changing a protected secret) need a fresh confirmation by a person. They are refused for tokens with step_up_session_only: do them in the console.

Good practice

  • One token per program, named after it; bind it to the areas it needs.

  • Use a service account for anything unattended, so it keeps working when a person leaves.

  • Rotate by making a new token, switching the program, then revoking the old one. Settings > Sessions and devices shows when each token was last used.

Download: PDF · Word · Markdown