API Keys & Sessions

External Deployments use two token types in sequence. Understanding why each exists helps you scope them correctly and limits the damage if one is ever exposed.

Two layers: rca_ keys and rds_ session tokens

Long-lived automation keys (rca_)

Automation keys are created once in the dashboard and stored as a GitHub repository secret. They authenticate the start of a deploy session — nothing more. An rca_ key with external_deploy in its allowed operations can only call POST /external-deploy/session and DELETE /external-deploy/session/{session_id}. It cannot read server state, execute commands, or perform 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 approximately 15 minutes.
• Is scoped to only the Applications matched during session creation — it cannot sync routes for other Applications in your tenant.
• Authorizes only POST /external-deploy/sync and DELETE /external-deploy/session/{session_id} (self-revocation).

The GitHub Action holds this token in memory for the duration of the sync step and never writes it to disk or to step outputs.

Why two layers?

The rca_ key lives in GitHub Secrets and is reused across every workflow run. If it were used directly for sync calls, a leaked key would give an attacker the ability to sync arbitrary proxy routes indefinitely until you notice and revoke it.

The rds_ token is created fresh each run and expires in 15 minutes regardless. An attacker who intercepts one (for example from a workflow log with set -x) can only affect the specific Applications in that session, and only until the token expires. By the time you see the log, the token is likely already expired.

The external_deploy operation

external_deploy is an allowed operation on an Automation Key, similar to exec or deploy. It grants the key permission to:

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

It does not grant permission to execute commands, restart containers, or perform any other server operation. A key with only external_deploy can do nothing other than open and close deploy sessions.

To add external_deploy to an existing key, go to API Keys > Automation Keys in the dashboard, click the key, and add external_deploy to Allowed Operations.

IP allowlist

Automation Keys support an IP allowlist. For workflows running on GitHub-hosted runners, you can restrict the key to GitHub’s runner IP ranges (the actions key in that response). This prevents the key from being usable from any other network even if it leaks.

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

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	~15 minutes (hard limit)	DELETE /external-deploy/session/{session_id} using either the rca_ key or the rds_ token itself

The GitHub Action calls DELETE /external-deploy/session/{session_id} automatically at the end of the workflow job (success or failure) to revoke 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 blast radius is limited to the Applications in that session — an attacker cannot route arbitrary domains.
2. The token expires in at most 15 minutes from creation, 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 immediately:

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 (external_deploy operation, same server scope and IP allowlist).
2. Update REOCLO_API_KEY in your GitHub repository secrets.
3. Verify 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 be used to sync routes on another server, so per-environment keys reduce the blast radius of any single exposure.

If the automation key is compromised

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