API Keys

Reoclo provides two types of API keys for different use cases:

• Integration Keys - for IDEs (Claude Code, Cursor, VS Code), MCP servers, and external tools that need broad access to your organization’s resources
• Automation Keys - for CI/CD systems (GitHub Actions, GitLab CI) that need to run specific operations on specific servers

Both key types are managed from a single page: API Keys in the dashboard sidebar. The page has two tabs.

Integration Keys

Integration keys provide ACL-based access to Reoclo’s API. Use them for IDE integrations, MCP servers, scripts, and any tool that needs to interact with your organization programmatically.

Creating an Integration Key

1. Navigate to API Keys in the dashboard
2. On the Integration Keys tab, click Create Integration Key
3. Enter a label (e.g., “Claude Code MCP”, “CI Read-Only”)
4. Choose an expiration: 30 days, 90 days, 1 year, or Never
5. Select a permission preset:

Preset	What it can access
Full Access	All resources, all actions. Use for trusted tools like your personal IDE.
Deploy Only	Applications (read + deploy), deployments (read), logs (read), dashboard (read).
Read Only	All resources, read-only. Cannot deploy or modify anything.
Custom	Choose exactly which resources and actions to allow.

6. Click Create
7. Copy the key immediately - it’s shown only once

Caution

The plaintext key is displayed only at creation time. If you lose it, you’ll need to create a new key and revoke the old one.

Custom Permissions

When you select Custom, you can choose permissions per resource:

Infrastructure:

• Servers: read, write, execute
• Domains: read, write

Applications:

• Applications: read, write, execute
• Deployments: read
• Environment Variables: read, write
• Repositories: read
• Registry Credentials: read, write

Observability:

• Logs: read
• Monitors: read, write
• Status Pages: read, write

Administration:

• Users: read, write
• Audit Logs: read
• Dashboard: read

Using Integration Keys

Include the key in the Authorization header:

curl -H "Authorization: Bearer rk_t_your_key_here" \
  https://app.reoclo.com/api/servers

IDE and MCP Setup

Claude Code / Cursor / VS Code - use the key with the Reoclo MCP server:

{
  "mcpServers": {
    "reoclo": {
      "command": "npx",
      "args": ["-y", "@reoclo/theta"],
      "env": {
        "REOCLO_API_KEY": "rk_t_your_key_here"
      }
    }
  }
}

This gives your AI assistant access to manage servers, applications, deployments, domains, logs, and more - scoped to whatever permissions you set on the key.

Automation Keys

Automation keys are designed for CI/CD pipelines. They’re scoped to specific servers and operations, with optional IP restrictions and rate limiting.

Creating an Automation Key

1. Navigate to API Keys in the dashboard
2. Switch to the Automation Keys tab
3. Click Create Automation Key
4. Enter a name (e.g., “github-prod-deploy”)
5. Configure server scope: select specific servers or allow all
6. Configure allowed operations: exec, deploy, restart, reboot, registry_login, registry_logout
7. Configure allowed registry credentials (for registry_login): select the registry credentials the key may pass to reoclo/docker-auth. Empty = all credentials in the tenant.
8. Select operations: deploy, restart, exec, reboot
9. Optionally expand Advanced Settings:
   • Expiration: 30 days, 90 days, 1 year, or Never
   • IP Allowlist: restrict to specific IPs or CIDR ranges (e.g., GitHub runner IPs)
   • Rate Limit: requests per minute (default: 100)
10. Click Create
11. Copy the key immediately - it’s shown only once

Using Automation Keys

With GitHub Actions - use reoclo/run and reoclo/checkout:

steps:
  - name: Checkout code on server
    uses: reoclo/checkout@v1
    with:
      api_key: ${{ secrets.REOCLO_API_KEY }}
      server_id: ${{ secrets.REOCLO_SERVER_ID }}
      token: ${{ github.token }}

  - name: Build and deploy
    uses: reoclo/run@v1
    with:
      api_key: ${{ secrets.REOCLO_API_KEY }}
      server_id: ${{ secrets.REOCLO_SERVER_ID }}
      working_directory: /opt/deploy/workspace
      command: |
        docker compose build
        docker compose up -d
      timeout: 600

With curl - use the Authorization: Bearer header:

curl -X POST https://app.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": "docker compose up -d",
    "timeout_seconds": 300
  }'

Automation Key Scoping

Best practice is to create separate keys for different environments and workflows:

Key Name	Servers	Operations	Use Case
github-prod-deploy	prod-1	deploy, restart	Production deploys from main branch
github-staging-all	staging-1	exec, deploy, restart	Staging: full access for testing
github-migrations	prod-1	exec	Run database migrations only
monitoring-restart	prod-1, prod-2	restart	Automated recovery scripts

Key Comparison

Feature	Integration Keys	Automation Keys
Prefix	rk_t_	rca_
Permissions	ACL matrix (resource x action)	Servers + operations
IP restriction	No	Yes
Rate limiting	No	Yes (configurable per-key)
Best for	IDEs, MCP servers, scripts, tools	CI/CD, GitHub Actions, automation
Dashboard tab	Integration Keys	Automation Keys
Min role to create	Developer	Manager

Managing Keys

Viewing Keys

The API Keys page shows all your keys with:

• Key label/name and prefix (for identification)
• Permission summary or server/operation scope
• Last used timestamp
• Status (Active, Expired, Revoked)

Revoking Keys

Click the revoke button on any key to invalidate it immediately. Revoked keys cannot be used for any API calls. In-flight operations using the key will complete, but new requests are rejected.

Rotating Keys

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

1. Create a new key with the same permissions
2. Update the key in your tools/CI secrets
3. Verify the new key works
4. Revoke the old key

If a Key Is Compromised

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

Next Steps

• GitHub Actions Integration to set up CI/CD with automation keys
• Automation API Reference for the full endpoint documentation
• API Overview for general API usage
• Access Control to understand organization roles