awslabs / awslabs/cli-agent-orchestrator

[Feat] Service accounts and an explicit API version

Open
#783 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.