# IAM CLI Commands

> The soat CLI commands for the IAM module, with usage and every option, generated from the OpenAPI spec.

# IAM Commands

See [IAM module docs](../../modules/iam) for permissions and data model.

### `soat check-iam-permission`

Check a permission of the calling credential

- Method: `POST`
- Path: `/api/v1/iam/check`

#### Usage

```bash
soat check-iam-permission --action <string> --resource <string>
```

#### Options

##### `--action`

A `module:Operation` action the deployment registered or a built-in one (`agents:DeleteAgent`); an unknown action or a wildcard is `400`.

- Source: `body`
- Required: yes
- Type: `string`
- Example: `channels:GetChannel`

##### `--resource`

`srn:<project_id>:<resource_type>:<id>`, where the type is one the action's module registered, or for a built-in action one its module's routes check it on, and `<id>` may be `*` for an action on no single resource (a create or a list). A `projects:*` action is checked on the whole project, `srn:<project_id>:*:*`, which takes no `context.tags`.

- Source: `body`
- Required: yes
- Type: `string`
- Example: `srn:proj_V1StGXR8Z5jdHi6B:channel:ch_1`

##### `--context`

What the conditions of a policy statement read.

- Source: `body`
- Required: no
- Type: `object`

### `soat create-iam-token`

Issue an IAM token

- Method: `POST`
- Path: `/api/v1/iam/tokens`

#### Usage

```bash
soat create-iam-token
```

#### Options

##### `--policy`

An inline policy document, validated as `POST /api/v1/policies` validates one (`400 IAM_TOKEN_POLICY_INVALID` otherwise). Work the token starts holds this snapshot.

- Source: `body`
- Required: no
- Type: `object`
- Example: `\{"statement":[\{"effect":"Allow","action":["agents:CreateAgentGeneration"]\}]\}`

##### `--policy-ids`

Policies of the key's project or global ones, read as they stand at each request. An unknown id is `400 IAM_TOKEN_POLICY_INVALID`.

- Source: `body`
- Required: no
- Type: `array<string>`
- Example: `["pol_V1StGXR8Z5jdHi6B"]`

##### `--principal`

A principal of the caller's own, opaque to the runtime.

- Source: `body`
- Required: no
- Type: `object`

##### `--tool-context`

A `tool_context` layer the token pins: on every tool call the token makes, and every call its work starts (generations, nested `builtin` and `soat` calls, `call-tool` relays), a caller key the layer names is dropped in any casing and the layer's value is sent instead. Admission sees the caller's own bag. Keys follow the `tool_context` key grammar and may not be a server identity key (`INVALID_TOOL_CONTEXT_KEY`). A key under the deployment's reserved prefix (`SOAT_RESERVED_TOOL_CONTEXT_PREFIX`) needs `iam:PinReservedToolContext` on `srn:<project_id>:iam_token:*`, else `400 INVALID_TOOL_CONTEXT_KEY`.

- Source: `body`
- Required: no
- Type: `object<string, string>`
- Example: `\{"tenant_id":"acct_42"\}`

##### `--ttl-seconds`

Seconds until the token expires.

- Source: `body`
- Required: no
- Type: `integer`
- Default: `300`

### `soat revoke-iam-principal`

Revoke a principal

- Method: `POST`
- Path: `/api/v1/iam/principal-revocations`

#### Usage

```bash
soat revoke-iam-principal --principal <object>
```

#### Options

##### `--project-id`

The project to revoke it in; defaults to the calling credential's project.

- Source: `body`
- Required: no
- Type: `string`
- Example: `proj_V1StGXR8Z5jdHi6B`

##### `--principal`

A principal of the caller's own, opaque to the runtime.

- Source: `body`
- Required: yes
- Type: `object`
