Give an agent access

This page gives a coding agent, or a script, its own key to your team’s clusters: with only the scopes it needs, connected over MCP or the REST API, and with every call it makes in a log you can read. A key belongs to one team and acts with the rights of the admin who created it.

In progress: not bookable yet

In progress The API keys, the MCP tools and the REST API are written and covered by the portal’s tests, but they have not run against a real cluster, and the portal is not live. Names can still change before it is. You cannot follow these steps yet. Tell me when it opens.

What you need

• The role of team admin. Only team admins can open API keys & agents and create keys.
• An MCP client, such as Claude Code, or curl for the REST API.
• For kubeconfigs: Python 3.10 or later with the cryptography package, where the agent runs.

Choose the scopes

Tick only what the agent needs. A scope never gives a key more than its creator may do in the team.

Scope	Allows	Tools
k3s:read	See clusters, their health, nodes, snapshots, operations, upgrades and add-ons.	list_clusters, get_cluster, list_snapshots, list_operations, get_operation, list_addons, list_projects, list_server_types
k3s:write	Take snapshots, schedule upgrades, switch or configure add-ons.	create_snapshot, schedule_upgrade, set_addon
k3s:access	Ask for temporary kubeconfigs, sealed to the agent’s own key, and revoke them.	request_kubeconfig, get_kubeconfig_result, revoke_access
k3s:destructive	Create, delete, detach and restore clusters, each only with the cluster’s name typed as confirmation.	create_cluster, delete_cluster, restore_snapshot, detach_cluster

An agent that only watches needs k3s:read. An agent that builds a throwaway cluster for a test, deploys to it and deletes it needs k3s:read, k3s:access and k3s:destructive, and k3s:write as well if it switches an add-on on, such as the PaaSbox Platform. A team’s first cluster is always created in the portal, because it starts the subscription; so is the first cluster after the team’s subscription has ended.

A key belongs to one team and reaches every cluster of it: no scope can be limited to one cluster. A key with k3s:destructive that may delete a throwaway cluster may also delete production in the same team. Keep production in a team the key does not belong to. The typed name a destructive call needs stops a mix-up, not a decision: the portal checks the name, not that you agreed. Whether your agent asks you first is up to its client.

Create the key

1. In the portal’s menu, open API keys & agents.

2. Under Create a key, enter a Name that says who uses it, for example claude-code. Tick the Scopes. Choose when it Expires: in 30 days, in 90 days (the default), in a year or never.

3. Choose Create key. Copy the key now: it is shown once and stored only as a hash. If you lose it, revoke it and create another. A team has at most 25 active keys.

Connect the agent

The page shows your team’s MCP endpoint and REST API addresses, and these snippets with them filled in.

For Claude Code:

claude mcp add --transport http paasbox https://<portal>/mcp/ \
  --header "Authorization: Bearer $PAASBOX_API_KEY"

For other MCP clients:

{
  "mcpServers": {
    "paasbox": {
      "type": "http",
      "url": "https://<portal>/mcp/",
      "headers": {"Authorization": "Bearer ${PAASBOX_API_KEY}"}
    }
  }
}

For the REST API:

curl -H "Authorization: Bearer $PAASBOX_API_KEY" https://<portal>/api/v1/teams/<team>/k3s/clusters/

Ask the agent to list your clusters. It sees only the tools its key’s scopes allow.

Get a kubeconfig for the agent

A kubeconfig for an agent is sealed to a key pair the agent makes, so the portal passes it on and cannot read it. The page offers the helper paasbox_kubeconfig.py, at /mcp/paasbox_kubeconfig.py on the portal. With the REST API it does everything in one command:

export PAASBOX_PORTAL=https://<portal> PAASBOX_API_KEY=<a key with k3s:access>
python3 paasbox_kubeconfig.py fetch --team <team> --cluster upcheck-prod --role admin > kubeconfig

Over MCP, the agent runs keygen, passes the public key to request_kubeconfig, takes the result with get_kubeconfig_result and runs decrypt (MCP tools). The kubeconfig lives 10 minutes to 24 hours, one hour by default.

Read what it did

Recent activity on the same page lists the last 20 calls; All activity lists every call, 50 a page, with a Key filter. Each row shows When, Key (and the person), Via (MCP or REST), Call (the tool or the REST operation), Cluster and Outcome: ok, or the error code of a refusal or failure, with the detail on hover.

Every MCP tool call is recorded, and every REST call that changes something or hands out a kubeconfig. Arguments are stored without secrets. What the agent does with a kubeconfig inside the cluster goes to the Kubernetes API directly and is not in this log.

Revoke a key

Choose Revoke next to the key. The agent is refused from its next call. A key also stops working when it expires, and when the person who created it leaves the team.

What next

Guardrails for agentsWhat scopes, confirmations, sealed kubeconfigs and the audit log stop, and what they do not.

3 · Let an agent test in its own clusterThe Learn step that puts this key to work.