# Operators

An operator can inspect and operate selected Keel applications without receiving an IAM user or a general-purpose AWS key. They sign in through a Cognito pool, can invoke only the [Keel control plane](./control-plane), and receive only the capabilities an administrator grants.

This is separate from both existing identity paths:

- IAM team members still assume the three account-wide Keel roles and provide the bootstrap and break-glass path.
- An `idp:` block in `keel.yml` gives users of an internal application a login; it does not grant access to Keel itself.

## Set up and enroll

An account administrator creates the operator provider and control plane once:

```bash
keel api deploy
keel auth idp setup --hosted-ui-prefix acme-keel
keel auth idp add alice@example.com
keel auth idp export
```

Cognito emails Alice a temporary password and requires MFA. `idp export` prints one account-wide sign-in token; it identifies where to sign in, not a person, and contains no secret. Send that line to the operator.

On Alice's machine:

```bash
keel auth idp login --token 'keel-idp-v1.…'  # needed once
keel api whoami
```

Keel remembers the provider, including after the session expires or `keel auth idp logout`, so later logins need no token. `logout --forget` removes that remembered provider too. `auth login`, `auth logout`, and `auth whoami` delegate to their operator equivalents when an operator session is the only plausible login.

## Grant capabilities

A new operator can do nothing until a row allows it. Name the operator by email or by the `prn_…` principal from `keel auth idp list`:

```bash
keel auth grants allow alice@example.com read     --app shop --env staging
keel auth grants allow alice@example.com logs     --app shop --env staging
keel auth grants allow alice@example.com exec     --app shop --env staging
keel auth grants deny  alice@example.com exec     --app shop --env production
keel auth grants list
```

A more specific row beats a wildcard, and a deny beats an allow at equal specificity. Rows govern only federated operators; IAM sessions are deliberately unaffected.

| Capability | Scope | Allows |
|---|---|---|
| `read` | app + environment | dashboard and live application state |
| `logs` | app + environment | application logs |
| `resource-logs` | app + environment | managed-resource logs such as database query logs |
| `exec` | app + environment | interactive container sessions |
| `scale` | app + environment | scale and restart; both are the same ECS authority |
| `rollback` | app + environment | select a task-definition revision that already exists |
| `config` | app + environment | read one value and set or unset config variables |
| `transcript` | app + environment | recorded exec session listings and transcripts |
| `platform` | shared platform | view shared-platform state independently of tenant access |
| `roster` | account | view the people roster |
| `audit` | account | view the complete authorization decision log |

Capabilities do not imply one another. `read` does not carry `logs`; `logs` does not carry `exec`; `scale` does not carry `rollback`; application access says nothing about the platform or roster.

## What works on an operator session

The dashboard, status, task lists, autoscaling state, config listing, histories, application and database logs, exec, config get/set/unset, scale, restart, rollback, session transcripts, shared-platform reads, roster reads, and audit decisions are wired through served or brokered routes.

Provisioning and authorization remain IAM operations. An operator cannot run OpenTofu (`up`, `infra apply`, platform changes, preview creation), bootstrap or destroy the control plane or IdP, manage grants, or enroll other people. A refusal says whether the command will never work on this identity or simply has no operator route yet.

Deploy is intentionally not brokered today. CodeBuild accepts build and environment overrides that cannot be constrained with IAM conditions, so handing a deploy credential to the client would amount to arbitrary code execution. Operators merge and let CI deploy, or an IAM team member starts the deploy.

## Suspend or remove

Suspension preserves the identity and every grant while immediately taking access out of force:

```bash
keel auth idp suspend alice@example.com
keel auth idp restore alice@example.com
```

Keel disables the pool user, revokes refresh tokens, and marks the roster binding disabled. A warm control-plane resolver may retain the old binding for at most 30 seconds.

Removal ends the enrollment and deletes its grants. Re-enrolling the same email creates a new principal so old authorization cannot return silently:

```bash
keel auth idp remove alice@example.com
```

The dashboard's Admin tab supports invitation, suspension, restoration, removal, grant editing, and the authorization decision log without leaving the TUI.