Skip to main content

IAM Commands

See IAM module docs for permissions and data model.

soat check-iam-permission​

Check a permission of the calling credential

  • Method: POST
  • Path: /api/v1/iam/check

Usage​

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​

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​

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