---
title: "Set Agent Role"
method: PUT
path: "/agents/{id}/role"
tags: ["agents"]
---

# Set Agent Role

`PUT /agents/{id}/role`

## Request

- Base URL: `https://api.instruxi.dev/api/v1/enforcer`
- URL: `https://api.instruxi.dev/api/v1/enforcer/agents/{id}/role`
- Auth: one of:
  - API key in header `Authorization`
  - API key in header `X-API-Key`

Changes the role of the agent's service account (manager() only). Fenced against the caller (403 role_exceeds_caller, role_not_allowed) and the steward (409 steward_role_too_low).

## Path parameters

- `id` string, required

## Request body

- InternalDeliveryHttpHandlerSetAgentRoleRequest
  - `role_id` string

## Response `200`

OK

- InternalDeliveryHttpHandlerAgentResponse
  - `data` EnforcerV3InternalUsecaseAgentsView
    - `card` object
    - `created_at` string
    - `created_by` string
    - `credentials` EnforcerV3InternalUsecaseAgentsCredentialRollup
      - `active` integer
      - `expiring_within_7d` integer
      - `last_used_at` string
    - `description` string
    - `effective_permissions` EnforcerV3InternalAuthzPermissions
      - `admin_managed` boolean: read/write/manage admin-managed types in tenant
      - `cross_tenant` boolean: every row, every tenant (admin)
      - `mpp_ops` boolean: MPPOps is a NARROW operator grant: read the MPP deposit-intent queue and its settle plans across tenants (GET /admin/mpp-deposit-intents...). It moves no money (the settle/refund levers stay PlatformOnly) and the policy never reads it: no row anywhere else becomes visible through it.
      - `tenant_manage` boolean: manage any non-admin-managed row in tenant
      - `tenant_read` boolean: read any non-admin-managed row in tenant
      - `tenant_write` boolean: write any non-admin-managed row in tenant
    - `expires_at` string
    - `groups` EnforcerV3InternalUsecaseAgentsGroupRef[]
      - `id` string
      - `name` string
      - `slug` string
    - `id` string
    - `name` string
    - `owner` EnforcerV3InternalUsecaseAgentsOwnerView
      - `id` string
      - `kind` 'account' | 'group'
      - `name` string
    - `rate_limit_per_min` integer
    - `role` EnforcerV3InternalUsecaseAgentsRoleView
      - `id` string
      - `permissions` EnforcerV3InternalAuthzPermissions
        - `admin_managed` boolean: read/write/manage admin-managed types in tenant
        - `cross_tenant` boolean: every row, every tenant (admin)
        - `mpp_ops` boolean: MPPOps is a NARROW operator grant: read the MPP deposit-intent queue and its settle plans across tenants (GET /admin/mpp-deposit-intents...). It moves no money (the settle/refund levers stay PlatformOnly) and the policy never reads it: no row anywhere else becomes visible through it.
        - `tenant_manage` boolean: manage any non-admin-managed row in tenant
        - `tenant_read` boolean: read any non-admin-managed row in tenant
        - `tenant_write` boolean: write any non-admin-managed row in tenant
      - `slug` string
    - `scopes` string[]
    - `service_account` EnforcerV3InternalUsecaseAgentsServiceAccountView
      - `active` boolean
      - `agent_id` string
      - `created_at` string
      - `created_by` string
      - `description` string
      - `email` string
      - `groups` EnforcerV3InternalUsecaseAgentsGroupRef[]
        - `id` string
        - `name` string
        - `slug` string
      - `id` string
      - `key_count` integer
      - `kind` string
      - `last_used_at` string
      - `name` string
      - `role` EnforcerV3InternalUsecaseAgentsRoleView
        - `id` string
        - `permissions` EnforcerV3InternalAuthzPermissions
          - `admin_managed` boolean: read/write/manage admin-managed types in tenant
          - `cross_tenant` boolean: every row, every tenant (admin)
          - `mpp_ops` boolean: MPPOps is a NARROW operator grant: read the MPP deposit-intent queue and its settle plans across tenants (GET /admin/mpp-deposit-intents...). It moves no money (the settle/refund levers stay PlatformOnly) and the policy never reads it: no row anywhere else becomes visible through it.
          - `tenant_manage` boolean: manage any non-admin-managed row in tenant
          - `tenant_read` boolean: read any non-admin-managed row in tenant
          - `tenant_write` boolean: write any non-admin-managed row in tenant
        - `slug` string
      - `slug` string
      - `tenant_id` string
      - `updated_at` string
    - `slug` string
    - `state` 'active' | 'disabled' | 'suspended'
    - `state_reason` string
    - `steward` EnforcerV3InternalUsecaseAgentsStewardView
      - `account_id` string
      - `email` string
      - `name` string
    - `tenant_id` string
    - `updated_at` string
  - `success` boolean

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `422`: Unprocessable Entity

---

[API](https://skmtc.dev/instruxi/apis/enforcer-api.md) · [All operations](https://skmtc.dev/instruxi/apis/enforcer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/instruxi/apis/enforcer-api/revisions/fa82bc1becc0?raw)