> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Attribute-Based Access Control (ABAC)

> Assign owners to agents with granular permissions - control who can invoke, configure, and delete each agent

ABAC lets you assign owners (users, teams, or service accounts) to agents with fine-grained permissions. This establishes clear accountability for every agent in your organization and controls who can perform actions on each agent.

## Owner Types

| Type              | Description          | Example             |
| ----------------- | -------------------- | ------------------- |
| `user`            | An individual user   | `alice@company.com` |
| `team`            | A team or department | `ml-platform-team`  |
| `service_account` | A machine identity   | `ci-cd-pipeline`    |

## Permissions

Each owner assignment includes a permissions object:

| Permission      | Description                                                  | Default |
| --------------- | ------------------------------------------------------------ | ------- |
| `can_invoke`    | Can send requests through the proxy as this agent            | `true`  |
| `can_configure` | Can update agent metadata, policies, and risk classification | `false` |
| `can_delete`    | Can delete the agent                                         | `false` |

## Assign an Owner

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.meshai.dev/api/v1/agents/01ARZ3NDEKTSV4RRFFQ69G5FAV/owners \
    -H "Authorization: Bearer msh_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "owner_type": "team",
      "owner_id": "ml-platform-team",
      "owner_name": "ML Platform Team",
      "permissions": {
        "can_invoke": true,
        "can_configure": true,
        "can_delete": false
      }
    }'
  ```

  ```python SDK theme={null}
  from meshai import MeshAI

  client = MeshAI(api_key="msh_...")

  client.assign_owner(
      agent_id="01ARZ3NDEKTSV4RRFFQ69G5FAV",
      owner_type="team",
      owner_id="ml-platform-team",
      owner_name="ML Platform Team",
      permissions={
          "can_invoke": True,
          "can_configure": True,
          "can_delete": False,
      },
  )
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": 1,
      "agent_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "owner_name": "ML Platform Team",
      "owner_type": "team"
    }
  }
  ```
</ResponseExample>

The assign response is intentionally minimal - `id`, `agent_id`, `owner_name`, and `owner_type`. Fetch the full record (including `owner_id` and `permissions`) via the list endpoint below.

## List Agent Owners

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.meshai.dev/api/v1/agents/01ARZ3NDEKTSV4RRFFQ69G5FAV/owners \
    -H "Authorization: Bearer msh_YOUR_API_KEY"
  ```

  ```python SDK theme={null}
  owners = client.list_agent_owners("01ARZ3NDEKTSV4RRFFQ69G5FAV")
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": 1,
        "owner_type": "team",
        "owner_id": "ml-platform-team",
        "owner_name": "ML Platform Team",
        "permissions": { "can_invoke": true, "can_configure": true, "can_delete": false }
      },
      {
        "id": 2,
        "owner_type": "user",
        "owner_id": "alice@company.com",
        "owner_name": "Alice Chen",
        "permissions": { "can_invoke": true, "can_configure": false, "can_delete": false }
      }
    ]
  }
  ```
</ResponseExample>

## Remove an Owner

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE https://api.meshai.dev/api/v1/agents/01ARZ3NDEKTSV4RRFFQ69G5FAV/owners/1 \
    -H "Authorization: Bearer msh_YOUR_API_KEY"
  ```

  ```python SDK theme={null}
  client.remove_owner(agent_id="01ARZ3NDEKTSV4RRFFQ69G5FAV", owner_id=1)
  ```
</CodeGroup>

## List Agents by Owner

Find all agents owned by a specific user, team, or service account:

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.meshai.dev/api/v1/owners/ml-platform-team/agents \
    -H "Authorization: Bearer msh_YOUR_API_KEY"
  ```

  ```python SDK theme={null}
  agents = client.list_owner_agents("ml-platform-team")
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "agent_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "permissions": { "can_invoke": true, "can_configure": true, "can_delete": false }
      },
      {
        "agent_id": "01BX5ZZKBKACTAV9WEVGEMMVRZ",
        "permissions": { "can_invoke": true, "can_configure": true, "can_delete": true }
      }
    ]
  }
  ```
</ResponseExample>

The response is a flat list of `{agent_id, permissions}` - it does not include the agent name; look it up separately via the agent registry if you need it for display.

## Audit Trail

ABAC actions (assigning or removing an owner) do not currently emit their own audit event. If you need a record of ownership changes, track them through your own tooling around the API calls.

## Use Cases

* **Non-human identity management** - Track the 144:1 ratio of NHIs to employees by assigning clear owners.
* **Team accountability** - Every agent has at least one owner responsible for its behavior.
* **Least-privilege access** - Grant `can_invoke` to runtime service accounts, `can_configure` to team leads only.
* **Compliance** - EU AI Act Article 14 requires human oversight - ABAC documents who oversees each agent.
* **Offboarding** - When a team member leaves, find all agents they own and reassign them.