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 | you, in the browser | signing in through REM Auth |
Personal access token |
| you | Settings > Tokens and secrets or Team > Access tokens > Create token |
Service-account token |
| 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 |
|---|---|
| API areas the token may call. Empty means every area. Areas: |
| Only this project's routes, MCP tools and git repository |
| The caller must send |
| Browser origins allowed (checked against |
| 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.