API keys and the API
Two kinds of key, and each side refuses the other:
rmk_ MCP key |
rmn_ API key |
|
|---|---|---|
| Opens | a group's workers | the console API |
| Sent as | Authorization: Bearer rmk_... on /mcp, or the bridge's --key |
X-Ramen-Api-Key: rmn_... on /api/v1/* |
| Made on | the group page, MCP auth keys → Generate key | the API keys page (super admins) |
| Scope | one group; pushed to its running workers when minted or revoked (1.0.0) | a role and groups, never wider than the creator's |
| Use for | agents, Claude Desktop, Cursor, curl |
CI deploys, rotation, backups, scripts |
Both are shown once and stored hashed: since 0.7.5 as s1$<salt>$<HMAC-SHA256> with a random salt per key (a key
hashed by an older release still verifies and is rewritten salted on its next use).
Revoke an MCP key on the group page (or DELETE $U/groups/<g>/mcp-keys/<id>) and the group's running workers
refuse it within seconds, no deploy needed (1.0.0, D92): the console pushes the group's key set and the revoked key's
SHA-256 to every zone of that group, the reload itself applies it, and the pods then restart with the new Secret.
Deleting an agent API key does the same in every group it reached. Minting a key is pushed the same way, so a rotation
is: generate the new key, switch the client, revoke the old one.
If a zone cannot be reached, the answer carries a warning and pending naming it, the group page shows
Revocation pending above the MCP keys, and the console retries in the background until it lands (a sleeping zone
picks it up when it wakes). Until then that zone still accepts the key.

The API and its Swagger page
Everything the console does is a JSON route under /api/v1. The OpenAPI UI is at https://<edge>/api/docs
(on the console's root: behind a path-prefix proxy it cannot load its schema, see
Configuration).
Authenticate with an API key, or with a session cookie plus the CSRF header:
curl -s -c c.txt -X POST https://<edge>/login --data-urlencode email=admin@ramen.local --data-urlencode password='...' -o /dev/null
CSRF="X-Ramen-CSRF: $(awk '$6=="ramen_csrf"{print $7}' c.txt)"
curl -s -b c.txt -H "$CSRF" -H 'Content-Type: application/json' -X POST https://<edge>/api/v1/api-keys \
-d '{"name":"ci-deploy","role":"group_admin","groups":["demo"]}' # 201 {"key":"rmn_..."}
Cheat sheet
One call in full, to copy and adapt:
curl -s -H "X-Ramen-Api-Key: $RMN" -H 'Content-Type: application/json' \
-X POST https://<edge>/api/v1/groups/demo/environments/prod/deploy -d '{"canary":true}'
The rest, with $U standing for https://<edge>/api/v1 and the same two headers on every call:
| Task | Call |
|---|---|
| Who am I | GET $U/me |
| Zones (super admin) | POST $U/zones {name,provider,region} |
| Groups | POST $U/groups {name,repo_url,ref}, DELETE $U/groups/{g} |
| Environments | POST $U/groups/{g}/environments {name,ref,zones}, PUT/DELETE .../environments/{e} |
| Deploy | POST .../environments/{e}/deploy {canary} gives 202 and an id, then GET $U/jobs/{id} until ok or error |
| Block tools | PUT .../environments/{e}/blocked {blocked:[...]}, then deploy |
| Workers | GET/PUT $U/groups/{g}/zones/{z}/workers {count,size} |
| IP rules, rebalance | PUT .../zones/{z}/ip-rules {cidrs}, POST .../zones/{z}/rebalance |
| Throttle, group and environment | PUT $U/groups/{g}/throttle {redis_url,ip_per_min,token_per_min} |
| Throttle, one item on one zone | PUT $U/groups/{g}/zones/{z}/item-throttle {redis_url,ip_per_min,token_per_min} |
| Secrets | POST $U/groups/{g}/secrets {name,value,env?,zone?}, DELETE .../secrets/{id} |
| MCP keys | POST $U/groups/{g}/mcp-keys {name} returns the key, DELETE .../mcp-keys/{id} |
| Members | POST $U/groups/{g}/members {email,role}, DELETE .../members/{id} |
| Permission requests | POST $U/requests {group,zone,permission,scope?}, POST $U/requests/{id}/approve, /deny, /revoke |
| OAuth clients | POST $U/oauth/clients {name,redirect_uris} |
| Logs | GET $U/logs?group=demo&zone=a&tail=500, and &download=1 for the file. Both names are required |
| Audit | GET $U/audit |
| Backups | POST $U/backups {target}, POST $U/backups/{id}/restore {dry_run,prune,reconcile} |
| Config | GET $U/config, POST $U/config/reload, PUT $U/config/auth |
A CI deploy job
JOB=$(eval $C -X POST $U/groups/demo/environments/prod/deploy -d "'{\"canary\":true}'" | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')
for i in $(seq 1 150); do
S=$(eval $C $U/jobs/$JOB | python3 -c 'import sys,json;print(json.load(sys.stdin)["status"])')
[ "$S" = ok ] && echo PASS && exit 0; [ "$S" = error ] && { eval $C $U/jobs/$JOB; exit 1; }; sleep 2
done; echo timeout; exit 1
Keep rmn_ keys in CI secrets. Deploy from GitHub Actions is the complete version of
this job: the key, the repo secret, a workflow that fails on a failed deploy, rotation. An agent operator can use
the agent skills instead.