feat: improve API keys and build workflows

README.md

@@ -86,6 +86,65 @@ The default login is scoped to the current user and the authenticated identity
 is available to every v2 command. `login`, `logout`, `whoami`, and global
 `maintenance` are the only commands that run without a loaded project configuration.
 
+### API Keys
+
+Create API keys for automation or other non-interactive clients. Keys belong to a
+user and carry explicit capabilities; use the smallest capability set the task
+needs. The `--workspace` option further restricts Kubernetes access to one
+workspace. Capabilities describe *what* the key may do, while workspace scope
+describes *where* its Kubernetes access applies; neither replaces the other.
+
+Valid capabilities are `kubernetes:read`, `kubernetes:write`,
+`kubernetes:exec`, `users:read`, `users:write`, `sessions:revoke`, and
+`platform:adopt`. For example, a deployment key that only reads and updates
+resources in the `website` workspace can be created with:
+
+```bash
+kuber users keys create deployer --capabilities kubernetes:read,kubernetes:write --workspace website
+```
+
+The default expiry is 90 days. Set `--expires-days` to an integer from 1 to 365,
+or explicitly use `none` for a key that does not expire:
+
+```bash
+kuber users keys create deployer --capabilities kubernetes:read --expires-days 30
+kuber users keys create deployer --capabilities kubernetes:read --expires-days none
+```
+
+The raw token is printed once at creation. Copy it directly into a secret
+manager; it cannot be retrieved later. List keys (optionally filtered by owner)
+to find the key ID, then revoke a compromised or retired key:
+
+```bash
+kuber users keys ls
+kuber users keys ls deployer
+kuber users keys revoke deployer <key-id>
+```
+
+Revoking a key immediately prevents it from authenticating. Do not place API
+tokens in source control, command-line arguments, or committed configuration.
+
+### CI Integration
+
+Create a dedicated automation user/key with only the capabilities required by
+the CI job, and set the token as a masked repository or organization secret
+(for example, `KUBER_API_TOKEN`). Expose the secret as an environment variable
+for the job step. Commands that use the v2 API can then authenticate with that
+token without an interactive `kuber login`:
+
+```yaml
+- name: Deploy with kuber
+  env:
+    KUBER_API_TOKEN: ${{ secrets.KUBER_API_TOKEN }}
+  run: kuber up
+```
+
+Use the CI provider's secret store, never commit the token or print it in logs.
+For example, a workspace-scoped key with `kubernetes:read,kubernetes:write`
+allows deployment operations in that workspace, but does not grant user
+administration, exec, or platform adoption. Add a capability only when the job
+needs that operation, and choose `--workspace` to limit its Kubernetes scope.
+
 ### Roles and Authorization
 
 The server grants capabilities through three roles: