API Keys

Integration keys retired

Reoclo has retired Tenant Integration Keys (rk_t_*). To connect IDEs and MCP clients, run reoclo login. It uses OAuth and issues no key. CI/CD pipelines still use Automation Keys (rca_*).

Automation Keys authenticate CI/CD pipelines. Two settings control what a key can reach:

• Operations are what the key can do: deploy an application, restart containers, run a shell command, read secrets.
• Scope is what the key can act on: the servers, registry credentials, and secret projects on the key.

A key can also carry an IP allowlist and a rate limit.

Operations now bind

The operation list on a key used to gate three routers only. Everywhere else, a key inherited the permissions of the person who created it.

A key now calls only the routes its operations cover. Every other endpoint returns 403 with the message Automation keys cannot use this endpoint.

A key with no operations can call nothing. Check every key you use. Add the operations each key needs.

Operations

Operation ids read as resource:verb. The dashboard groups them and marks each one with a risk level.

Operation	Dashboard label	What the key can do	Risk
application:deploy	Deploy	Deploy an application.	standard
deploy_session:open	Open a deploy session	Open a short-lived deploy session. A CI workflow that builds and runs the containers itself uses the session to sync proxy routes.	elevated
container:restart	Restart containers	Restart the containers of an application.	standard
server:exec	Run shell commands	Run a shell command on a server.	critical
server:terminal	Open a terminal	Open an interactive terminal session on a server.	critical
server:reboot	Reboot servers	Reboot a server. Every container on the server stops.	critical
secret_session:open	Read secrets	Open a short-lived, read-only secret session for one CI run.	critical
registry:login	Registry sign-in	Sign in to a container registry on a server.	standard
registry:logout	Registry sign-out	Sign out of a container registry at the end of a workflow run.	standard

The risk level tells you what a leaked key costs you:

Risk	Meaning
standard	Reads, and routine writes that a deployment does anyway.
elevated	Changes or destroys state that a person would want to review.
critical	Runs arbitrary code, or reads production credentials.

Two operations need more than the operation itself. registry:login reads the allowed registry credentials on the key. secret_session:open reads the secret projects granted to the key.

Reading secrets

secret_session:open lets a key open a short-lived, read-only secret session for one CI run. The session reads only the secret projects granted to that key.

An automation key can never create, change, roll back, or delete a secret. Grant each secret project on its Access tab. See Secrets in CI.

The server scope does not narrow this operation, because a secret session targets no server.

Old operation names

Keys created before this change hold flat names such as deploy and exec. Reoclo accepts those names as aliases, so existing keys and workflow files keep working. The dashboard shows the canonical name.

Old name	Canonical operation
deploy	application:deploy
restart	container:restart
exec	server:exec
reboot	server:reboot
terminal	server:terminal
registry_login	registry:login
registry_logout	registry:logout
external_deploy	deploy_session:open

secret_session:open is new and has no old name.

Presets

The create form offers a preset as a starting point. Pick one, then add or remove operations.

Preset	Operations
Deploy from GitHub Actions	application:deploy, container:restart, registry:login, registry:logout
Deploy a build you made yourself	deploy_session:open, registry:login, registry:logout
Read secrets in CI	secret_session:open
Start from nothing	none

Creating an Automation Key

1. Open Automation Keys in the dashboard sidebar.
2. Click Create Automation Key.
3. Enter a name, for example github-prod-deploy.
4. Pick a preset, or start from nothing.
5. Set the allowed operations. Add every operation the pipeline calls.
6. Set the server scope. Select specific servers, or allow all.
7. For registry:login, set the allowed registry credentials. An empty list allows every credential in the tenant.
8. Optionally open Advanced Settings:
   • Expiration: 30 days, 90 days, 1 year, or Never.
   • IP Allowlist: restrict the key to specific IPs or CIDR ranges, such as GitHub runner IPs.
   • Rate Limit: requests each minute. The default is 100.
9. Click Create.
10. Copy the key now. Reoclo shows the plaintext key one time only.

If the key needs secret_session:open, grant each secret project separately. Open the project and add the key on its Access tab.

Caution

Reoclo shows the plaintext key at creation time only. If you lose the key, create a new key. Then revoke the old one.

Using Automation Keys

With GitHub Actions

Use reoclo/run and reoclo/checkout:

steps:
  - name: Checkout code on server
    uses: reoclo/checkout@v2
    with:
      api_key: ${{ secrets.REOCLO_AUTOMATION_KEY }}
      server_id: ${{ secrets.REOCLO_SERVER_ID }}
      path: /srv/reoclo/myapp
      token: ${{ github.token }}

  - name: Build and deploy
    uses: reoclo/run@v2
    with:
      api_key: ${{ secrets.REOCLO_AUTOMATION_KEY }}
      server_id: ${{ secrets.REOCLO_SERVER_ID }}
      working_directory: /srv/reoclo/myapp
      command: |
        docker compose -f docker-compose.prod.yml build
        docker compose -f docker-compose.prod.yml up -d
      timeout: 600

Both steps call /exec, so the key needs server:exec.

With curl

curl -X POST https://api.reoclo.com/api/automation/v1/exec \
  -H "Authorization: Bearer rca_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "your-server-id",
    "command": "cd /srv/reoclo/myapp && docker compose -f docker-compose.prod.yml up -d",
    "timeout_seconds": 300
  }'

With the Reoclo CLI in CI

To use the full CLI rather than reoclo/run or reoclo/checkout, set REOCLO_AUTOMATION_KEY in the environment:

- name: Deploy via reoclo CLI
  env:
    REOCLO_AUTOMATION_KEY: ${{ secrets.REOCLO_AUTOMATION_KEY }}
  run: |
    npx -y @reoclo/cli apps deploy my-app --ref ${{ github.sha }}

The CLI honors REOCLO_AUTOMATION_KEY for unattended use without invoking OAuth.

Credentials reference

Every integration method authenticates with the same Automation Key (rca_*). Only the variable name, the target identifier, and the operations differ. Use this table to pick the right secret and target for the method you are wiring up.

Method	Key passed as	Secret / env var	Target identifier	Operations needed
GitHub Action: reoclo/run, reoclo/checkout	api_key input	secret REOCLO_AUTOMATION_KEY	server_id input, from secret REOCLO_SERVER_ID	server:exec
GitHub Action: reoclo/docker-auth	api_key input	secret REOCLO_AUTOMATION_KEY	server_id input	registry:login, registry:logout
GitHub Action: reoclo/deploy-sync	api_key input	secret REOCLO_AUTOMATION_KEY	none, matches services by container name	deploy_session:open
Reoclo CLI in CI	environment variable	REOCLO_AUTOMATION_KEY	CLI argument, --server <name> or apps deploy <app>	depends on the command
REST Automation API	Authorization: Bearer <key> header	header value	server_id in the body, or application_id for deploy	one per endpoint

One key type for all automation

All these methods use an Automation Key (rca_*). Reoclo no longer issues Tenant Integration Keys (rk_t_*). For IDE and MCP access, run reoclo login instead of using any key.

Legacy secret name

If your CI secret is still named REOCLO_API_KEY, keep passing it to the action’s api_key input. The CLI reads REOCLO_AUTOMATION_KEY only.

Example keys

Create separate keys for different environments and workflows:

Key name	Servers	Operations	Use case
github-prod-deploy	prod-1	application:deploy, container:restart	Production deploys from the main branch
github-staging-all	staging-1	server:exec, application:deploy, container:restart	Staging, where a workflow needs full access
github-migrations	prod-1	server:exec	Database migrations only
monitoring-restart	prod-1, prod-2	container:restart	Automated recovery scripts
ci-secrets	none	secret_session:open	Read secrets in CI, with no deploy rights

Working with existing keys

Viewing keys

The Automation Keys page lists every key with:

• Name and prefix, which identify the key
• Operations and scope
• Last used timestamp
• Status: Active, Expired, or Revoked

Editing a key

Open a key to change its name, operations, server scope, registry credentials, IP allowlist, rate limit, or expiry date. A change takes effect on the next request, so there is no need to rotate the key.

Editing the expiry date now works. Earlier versions reported success and changed nothing.

Revoking keys

Click the revoke button on any key to invalidate it immediately. A revoked key fails every API call. Operations that already started finish, and Reoclo rejects every new request.

Rotating keys

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

1. Create a new key with the same operations and scope.
2. Update the key in your CI secrets.
3. Check that the new key works.
4. Revoke the old key.

If a key is compromised

1. Revoke the key immediately from the Automation Keys page.
2. Create a replacement key.
3. Update all CI secrets that used the old key.
4. Read the Audit Log for unauthorized operations made with the compromised key.

IDE and MCP access

For Claude Code, Cursor, VS Code, or any other MCP client, do not use an Automation Key. Run reoclo login and configure the CLI MCP server. See the MCP Setup guide.

Next Steps

• CLI Authentication: reoclo login for IDE and MCP access
• MCP Setup: connect Claude Code, Cursor, VS Code, and others
• GitHub Actions Integration: CI/CD with Automation Keys
• Automation API Reference: endpoint documentation