API Keys & Sessions

External Deployments use two token types in sequence. Each type limits the damage if the other one leaks.

Two layers: rca_ keys and rds_ session tokens

Long-lived automation keys (rca_)

You create an automation key in the dashboard, then store it as a GitHub repository secret. It authenticates the start of a deploy session, and nothing more.

A key with the deploy_session:open operation calls POST /external-deploy/session and DELETE /external-deploy/session/{session_id}. It cannot read server state, run commands, or do any other operation on its own.

Short-lived deploy session tokens (rds_)

When POST /external-deploy/session succeeds, Reoclo issues an rds_ session token. This token:

• Is valid for about 15 minutes.
• Covers only the applications matched at session creation. It cannot sync routes for other applications in your tenant.
• Authorizes POST /external-deploy/sync, GET /external-deploy/status, and DELETE /external-deploy/session/{session_id} for self-revocation.

The GitHub Action holds this token in memory for the sync step. It never writes the token to disk or to step outputs.

Why two layers?

The rca_ key lives in GitHub Secrets, and every workflow run reuses it. Direct sync calls with that key would be worse. A leaked key would let an attacker sync arbitrary proxy routes until you notice and revoke it.

Reoclo mints a fresh rds_ token each run, and the token expires in 15 minutes. An attacker who intercepts one affects only the applications in that session, and only until it expires. A workflow log with set -x is the usual leak. By the time you read that log, the token has most likely expired.

The deploy_session:open operation

deploy_session:open is an operation on an Automation Key, like server:exec or application:deploy. It lets the key:

1. Create deploy sessions (POST /external-deploy/session).
2. Revoke deploy sessions (DELETE /external-deploy/session/{session_id}).

It does not let the key run commands, restart containers, or do any other server operation. A key with deploy_session:open alone opens and closes deploy sessions, and nothing else.

To add the operation to an existing key, open API Keys > Automation Keys in the dashboard. Click the key, then add deploy_session:open to Allowed Operations.

The old name still works

Keys created earlier hold the flat name external_deploy. Reoclo accepts it as an alias, so those keys and their workflow files keep working. The dashboard shows deploy_session:open.

POST /external-deploy/sync and GET /external-deploy/status still need an rds_ session token. The operation on the rca_ key does not authorize those two calls by itself.

IP allowlist

Automation Keys carry an optional IP allowlist. For workflows on GitHub-hosted runners, restrict the key to GitHub’s runner IP ranges. Read the actions key in that response. A leaked key then fails from every other network.

Session tokens (rds_) inherit the IP restriction of the rca_ key that created them. If that key has an IP allowlist, the session token works from those same IPs only.

Expiry and revocation

Token	Expiry	Revocation
rca_ automation key	Configurable: 30 days, 90 days, 1 year, or Never	Dashboard: API Keys page, revoke button
rds_ session token	About 15 minutes, a hard limit	DELETE /external-deploy/session/{session_id}, using either the rca_ key or the rds_ token itself

Editing the expiry date of an existing rca_ key now works. Earlier versions reported success and changed nothing.

The GitHub Action calls DELETE /external-deploy/session/{session_id} at the end of the workflow job, on success and on failure. That revokes the session immediately rather than waiting for it to expire.

What happens if an rds_ token leaks

If a session token appears in a workflow log, a debug trace, or any other output:

1. The damage reaches only the applications in that session. An attacker cannot route arbitrary domains.
2. The token expires at most 15 minutes after creation, and often sooner by the time you notice.
3. If you see a leaked token before it expires, call DELETE /external-deploy/session/{session_id} with your rca_ key to revoke it:

curl -X DELETE https://api.reoclo.com/external-deploy/session/SESSION_ID \
  -H "Authorization: Bearer rca_example_DO_NOT_USE_xxxxxxxxxxxxxx"

You do not need to rotate the rca_ key unless it was also exposed.

Rotating the automation key

There is no in-place rotation. To rotate an rca_ key:

1. Create a new Automation Key with the same settings: the deploy_session:open operation, the same server scope, and the same IP allowlist.
2. Update REOCLO_AUTOMATION_KEY in your GitHub repository secrets.
3. Check that the next workflow run succeeds.
4. Revoke the old key from the dashboard.

Tip

Create separate rca_ keys for separate repositories or environments. A key scoped to one server cannot sync routes on another server. Keys for each environment reduce the damage from any single exposure.

If the automation key is compromised

1. Revoke the key immediately from the API Keys page in the dashboard.
2. Active rds_ sessions created with that key become invalid within seconds. Reoclo propagates key revocations to session validity checks.
3. Create a replacement key and update your secrets.
4. Read the Audit Log for session creations or sync calls made with the compromised key.