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

# Agent grants API (organization)

> Share agents with users and other agents, make them public, rename them, and transfer ownership, with org unit and organization sharing.

> [!NOTE]
>
> **Plans:** Free, Individual, Pro, and Enterprise. **Self-hosted:** Enterprise license.

Nasiko Cloud and self-hosted Enterprise servers serve these grants routes at `/api/agents/{id}/...`. Some paths match a self-hosted open-source server's, but the request shapes differ: user and agent grants take the grantee in the path, not the body. For the open-source routes, see [Agent access API](https://docs.nasiko.com/api-reference/agent-access.md).

On Free, making an agent public, granting it to an org unit or the organization, and transferring its ownership return `402` with code `plan_feature_not_included`.

Behavioral guide: [User → agent access](https://docs.nasiko.com/governance/access-control/agent-access.md). The dashboard's **Access** tab and, on Enterprise deployments, `nasiko-ee access` call these routes.

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/api/agents/{id}/grants` | Every grant on the agent |
| `GET` | `/api/agents/{id}/visibility` | The public flag plus every grant |
| `GET` | `/api/agents/{id}/users` | Users who can reach the agent |
| `GET` | `/api/agents/{id}/accessible-agents` | Agents this agent can reach |
| `POST` `DELETE` | `/api/agents/{id}/grants/users/{user_id}` | Share with, or unshare from, a user |
| `POST` `DELETE` | `/api/agents/{id}/grants/agents/{target_id}` | Share with, or unshare from, another agent |
| `POST` `DELETE` | `/api/agents/{id}/grants/units/{unit_id}` | Share with, or unshare from, an org unit and every unit beneath it |
| `POST` `DELETE` | `/api/agents/{id}/grants/organization` | Share with, or unshare from, every signed-in user |
| `POST` `DELETE` | `/api/agents/{id}/grants/public` | Make public, or private |
| `PUT` | `/api/agents/{id}/name` | Rename |
| `PUT` | `/api/agents/{id}/owner` | Transfer ownership |

## Who can call

Every route needs a session (`Authorization: Bearer <token>`) from the agent's owner, a user with the `admin` role, or a superuser, except the org unit and organization grants below. The `GET` routes answer anyone else with `200` and `{"available": false}`. Write routes answer `403`:

```json theme={null}
{ "error": "not the agent owner" }
```

Sharing, making public, and transferring ownership of a coding agent's harness agent are refused with `409`:

```json theme={null}
{ "error": "harness agents belong to one user and cannot be shared", "code": "agent_not_shareable" }
```

Revoking a grant is always allowed. Every agent and user ID is a UUID.

## Read grants

`GET /api/agents/{id}/grants`

```json theme={null}
[
  {
    "id": "c3f1...",
    "agent_id": "a1b2...",
    "grant_type": "user",
    "grantee_id": "5b1e2c4a-...",
    "granted_by": null,
    "created_at": "2026-11-10T09:00:00Z"
  },
  { "id": "d47e...", "agent_id": "a1b2...", "grant_type": "org_unit", "grantee_id": "9a1c...", "granted_by": null, "created_at": "2026-11-11T09:00:00Z" }
]
```

| Field | Description |
| - | - |
| `grant_type` | `user`, `org_unit`, `organization`, `agent`, or `public` |
| `grantee_id` | The user, unit, or agent ID. `*` for `organization` and `public` |

Sorted by type, then creation time.

`GET /api/agents/{id}/visibility` returns the same grants with the public flag:

```json theme={null}
{ "agent_id": "a1b2...", "is_public": false, "grants": [ { "grant_type": "user", "grantee_id": "5b1e2c4a-...", "...": "..." } ] }
```

`404` if the agent doesn't exist.

`GET /api/agents/{id}/users` lists everyone who can reach the agent through ownership, a user grant, or an org unit grant:

```json theme={null}
[ { "id": "5b1e2c4a-...", "username": "alice", "email": "alice@acme.com", "role": "member" } ]
```

`GET /api/agents/{id}/accessible-agents` lists the public agents and the agents shared with this agent:

```json theme={null}
[ { "id": "e9f0...", "name": "billing", "description": "Invoices", "is_public": false } ]
```

## Share with a user or agent

`POST /api/agents/{id}/grants/users/{user_id}` and `POST /api/agents/{id}/grants/agents/{target_id}`

No body. `201` on success, including when the grant already exists.

```bash theme={null}
curl -X POST https://<your-host>/api/agents/a1b2.../grants/users/5b1e2c4a-... \
  -H "Authorization: Bearer <token>"
```

Sharing with an agent adds this agent to the agents `target_id` can reach. It doesn't change which agents may call which.

`DELETE` the same path to revoke. `204` on success, `404` if there was no such grant.

## Share with an org unit or the organization

`POST /api/agents/{id}/grants/units/{unit_id}` shares the agent with everyone in the unit and every unit beneath it. You can make or revoke this grant if you have the `admin` role, lead the unit or a unit above it, or own the agent and belong to the unit. Anyone else gets `403`.

`POST /api/agents/{id}/grants/organization` shares the agent with every signed-in user of the deployment. It needs the `admin` role or a superuser; anyone else gets `403`. It doesn't make the agent public.

No body. `201` on success. `DELETE` the same path to revoke: `204`, or `404` if there was no such grant.

## Public or private

`POST /api/agents/{id}/grants/public` makes the agent reachable by every signed-in user. `201`.

`DELETE /api/agents/{id}/grants/public` makes it private. `204`, or `404` if the agent doesn't exist. Nasiko's own built-in harness agents stay public, and making one private returns `409` with `"code": "agent_not_shareable"`.

## Rename

`PUT /api/agents/{id}/name`

| Body field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | New name. Leading and trailing spaces are trimmed |

`204` on success. `400` with `name cannot be empty`. `404` if the agent doesn't exist. `409` with `"code": "agent_not_renamable"` for a harness agent.

## Transfer ownership

`PUT /api/agents/{id}/owner`

| Body field | Type | Required | Description |
| - | - | - | - |
| `owner_id` | UUID | Yes | The new owner |

```bash theme={null}
curl -X PUT https://<your-host>/api/agents/a1b2.../owner \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"owner_id": "7d2a..."}'
```

| Status | Meaning |
| - | - |
| `204` | Transferred |
| `400` | `{"error": "the new owner does not exist"}` or `{"error": "the new owner is deactivated"}` |
| `404` | No such agent |
| `409` | `{"error": "the new owner already has an agent with this name — rename one of them first"}`, or a harness agent |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.