> ## 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 access API

> Share an agent with users, make it public, and set which agents it may call.

These routes decide who can reach one of your agents, and which other agents it may call. They aren't in the generated OpenAPI spec. The dashboard's **Access** tab on an agent page calls them. Behavior guide: [User → agent access](https://docs.nasiko.com/governance/access-control/agent-access.md).

> [!NOTE]
>
> This page documents a self-hosted open-source server. Nasiko Cloud, on every plan, and self-hosted Enterprise servers serve a different grants API at these same paths, with org unit and organization sharing. See [Agent grants API](https://docs.nasiko.com/api-reference/enterprise/agent-grants.md).

## Authentication and permissions

Every route takes a session JWT in `Authorization: Bearer <token>` (from `POST /api/auth/login`) or the dashboard cookie. A missing or expired token returns `401`.

Every route, reads included, requires that you **own the agent** or are a superuser. Anyone else gets `403` with an empty body, including when the agent doesn't exist or was deleted. Being able to chat with an agent doesn't let you see or change its access.

| Path parameter | Description |
| - | - |
| `id` | The agent's UUID |

## How access works

On a self-hosted open-source server, a user can reach an agent when any of these is true:

* They own it.
* It's public.
* It has a user grant naming them.

Grants are additive and only widen access. Ownership is never transferred by a grant, and only the owner or a superuser can change the agent.

An **agent grant** is separate. It's an allowlist of the agents this agent may call through Nasiko. An agent with no agent grants may call any agent its user can reach. Once you add one agent grant, the agent may call only the agents you've listed.

Harness agents belong to one user and can't be shared. Writes that would share one return `409`:

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

## Get an access summary

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

Everything about the agent's access in one call.

```bash theme={null}
curl https://nasiko.example.com/api/agents/8d3c0f6e-2b1a-4c9e-9f7d-1a2b3c4d5e6f/grants \
  -H "Authorization: Bearer $NASIKO_TOKEN"
```

**Response** `200 OK`

```json theme={null}
{
  "agent_id": "8d3c0f6e-2b1a-4c9e-9f7d-1a2b3c4d5e6f",
  "is_public": false,
  "user_grants": ["4a1b2c3d-5e6f-4789-8abc-def012345678"],
  "agent_acl": ["c0ffee00-1111-4222-8333-444455556666"]
}
```

| Field | Description |
| - | - |
| `is_public` | Whether every user can reach the agent |
| `user_grants` | IDs of users granted access |
| `agent_acl` | IDs of agents this agent may call. Empty means no allowlist is set |

## Get visibility

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

Only the public flag.

**Response** `200 OK`

```json theme={null}
{ "agent_id": "8d3c0f6e-2b1a-4c9e-9f7d-1a2b3c4d5e6f", "is_public": true }
```

A superuser gets `404` with an empty body when the agent doesn't exist or was deleted.

## Make public or private

`POST /api/agents/{id}/grants/public`
`DELETE /api/agents/{id}/grants/public`

`POST` makes the agent reachable by every user on the server. `DELETE` makes it private again. User grants are unaffected either way. Both are idempotent.

```bash theme={null}
curl -X POST https://nasiko.example.com/api/agents/8d3c0f6e-2b1a-4c9e-9f7d-1a2b3c4d5e6f/grants/public \
  -H "Authorization: Bearer $NASIKO_TOKEN"
```

**Response** `204 No Content`

**Errors**

| Status | When |
| - | - |
| `403` | You don't own the agent |
| `404` | Superusers only: the agent doesn't exist or was deleted |
| `409` | `POST`: the agent is a harness agent (`agent_not_shareable`). `DELETE`: the agent is one of the server's own harness agents, which stay public. The body is `{ "error": "the platform's harness agents stay public", "code": "agent_not_shareable" }` |

## List user grants

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

The users granted access. The two paths return the same list.

**Response** `200 OK`

```json theme={null}
[
  { "user_id": "4a1b2c3d-5e6f-4789-8abc-def012345678", "username": "alice" },
  { "user_id": "9b8a7c6d-5e4f-4321-8fed-cba987654321", "username": null }
]
```

`username` is `null` when the user has been deleted. The grant can still be removed.

## Grant a user access

`POST /api/agents/{id}/grants/users`

Lets one user reach the agent: chat with it, see it in the catalog, and read its details. It gives no right to change it. Idempotent: granting the same user twice changes nothing.

| Field | Type | Required | Description |
| - | - | - | - |
| `user_id` | UUID | Yes | The user to grant. Find IDs with `GET /api/search/users` |

```bash theme={null}
curl -X POST https://nasiko.example.com/api/agents/8d3c0f6e-2b1a-4c9e-9f7d-1a2b3c4d5e6f/grants/users \
  -H "Authorization: Bearer $NASIKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "4a1b2c3d-5e6f-4789-8abc-def012345678"}'
```

**Response** `201 Created` with an empty body.

**Errors**

| Status | When |
| - | - |
| `403` | You don't own the agent |
| `404` | `user not found` |
| `409` | The agent is a harness agent (`agent_not_shareable`) |

## Revoke a user's access

`DELETE /api/agents/{id}/grants/users/{user_id}`

| Path parameter | Description |
| - | - |
| `user_id` | The user whose grant to remove |

**Response** `204 No Content`. Removing a grant that doesn't exist also returns `204`.

## List agent grants

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

The agents this agent may call.

**Response** `200 OK`

```json theme={null}
[
  { "target_agent_id": "c0ffee00-1111-4222-8333-444455556666", "target_name": "billing-agent" }
]
```

`target_name` is `null` when the target agent has been deleted.

## Allow calls to an agent

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

Adds an agent to this agent's call allowlist. Once the list has any entry, calls through Nasiko from this agent to an agent not on the list return `403`. Idempotent.

| Field | Type | Required | Description |
| - | - | - | - |
| `agent_id` | UUID | Yes | The agent this agent may call |

```bash theme={null}
curl -X POST https://nasiko.example.com/api/agents/8d3c0f6e-2b1a-4c9e-9f7d-1a2b3c4d5e6f/grants/agents \
  -H "Authorization: Bearer $NASIKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "c0ffee00-1111-4222-8333-444455556666"}'
```

**Response** `201 Created` with an empty body.

**Errors**

| Status | When |
| - | - |
| `403` | You don't own the calling agent |
| `404` | `target agent not found` |

## Remove an allowed agent

`DELETE /api/agents/{id}/grants/agents/{target_agent_id}`

| Path parameter | Description |
| - | - |
| `target_agent_id` | The agent to remove from the allowlist |

**Response** `204 No Content`. Removing the last entry lifts the allowlist, so the agent may call any agent its user can reach.

## Related

* [User → agent access](https://docs.nasiko.com/governance/access-control/agent-access.md)
* [Access control reference](https://docs.nasiko.com/governance/access-control/reference.md)
* [MCP gateway](https://docs.nasiko.com/build/mcp/overview.md) for connector grants, which use a similar shape under `/api/mcp/connectors/{id}/grants`


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