awslabs / awslabs/cli-agent-orchestrator
[Feat] Service accounts and an explicit API version
- Dominant language
- Python
- Stars
- 1.3k
- Forks
- 267
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 70
Description
Part of #777. **After 3.0.**
Service accounts build on #778's tenants, #774's stable identity/ownership and #779's membership/permission lifecycle. Audit attribution depends on #782. The public API versioning work is a separate part of this issue and can be designed independently.
## In plain terms
Two gaps that only start to hurt once CAO is a shared service other things depend on.
**CAO has no tenant-managed service accounts.** Machine access already exists: the shared `CAO_ELASTIC_BROKER_TOKEN` authorises broker-management calls, and each worker gets a separately generated `CAO_ELASTIC_RELEASE_TOKEN`, checked against that worker's Deployment (`examples/cao-clusters/kubernetes/eks/broker.py:1035-1079`, `:1265-1273`). Those are different credentials with different authority; neither is a managed service account belonging to a tenant with its own role and account lifecycle. The missing capability is an independently managed automation identity, not an inability for machines to make authenticated calls.
**The core HTTP API has no overall versioning and compatibility contract.** Some surfaces are already versioned: AG-UI uses `/agui/v1/stream`, `/agui/v1/emit_ui` and `/agui/v1/run` (`api/main.py:1709`, `:1968`, `:2117`). The core session, terminal and workflow routes remain unversioned. Pipelines, scripts and other clients of a shared CAO upgrade independently, so this issue needs to define compatibility across those surfaces rather than assume no versioned endpoint exists.
## What this delivers
**Service accounts that belong to a tenant**, with their own roles, usable for automation, and revocable without touching a person's account.
An automation account has its own stable identity and owned resources or explicit grants under the same tenant/visibility policy. Its creator, current caller and resource owner are not interchangeable. Define what happens to its queued/running work and retained data on revocation, reusing #779's bounded cancellation/cleanup rules where applicable.
**Short-lived service-account credentials by preference.** Independent account management is the new capability here. Restricted, task-bound agent credentials and request-scoped runtime identity are already required in 3.0 by #774/#745; they must not wait for this ticket.
**An explicit API version and a compatibility promise** — what may change without notice, what may not, and how long an old version is supported.
This is the later, overall public API contract. It does not postpone #745/#776's 3.0 server/runtime/MCP compatibility and upgrade requirements. Keep core HTTP API versions, MCP protocol revisions, terminal stream generations and database schema versions distinct; they solve different compatibility problems.
## Acceptance criteria
- [ ] A service account can be created within a tenant, given a role, and revoked independently of any person.
- [ ] Its identity, permissions and retained ownership do not silently become those of its human creator; revocation has explicit queued/running-work and cleanup outcomes.
- [ ] Service account actions are attributable in the audit trail.
- [ ] Credentials are short-lived by default, with rotation documented.
- [ ] The API carries an explicit version.
- [ ] The compatibility promise is written down.
- [ ] Existing public clients have a documented transition/deprecation path. This work preserves rather than retroactively supplies the component/protocol compatibility needed by 3.0.
- [ ] On a laptop, none of this is needed and nothing changes.
## Evidence
| Claim | Where |
| --- | --- |
| No tenant-managed service accounts | Shared broker-management credentials and per-worker credentials already exist; neither supplies tenant service-account records and lifecycle |
| No overall core API versioning contract | Core session/terminal/workflow routes are unversioned; AG-UI already has `/agui/v1` routes |
Contributor guide
Research direction
Start with the core routes in api/main.py and the broker credential paths in examples/cao-clusters/kubernetes/eks/broker.py:1035-1079 and :1265-1273. Read the linked tenant, identity, membership, permission and audit work (#778, #774, #779 and #782) before defining the service-account and API-version boundaries. Done means all listed acceptance criteria, including revocation behavior, audit attribution, compatibility documentation and no laptop-mode changes, are addressed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kubernetes, python
- Domain
- authentication, authorization, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100