Skip to main content
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.
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.

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.

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:

Get an access summary

GET /api/agents/{id}/grants Everything about the agent’s access in one call.
Response 200 OK

Get visibility

GET /api/agents/{id}/visibility Only the public flag. Response 200 OK
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.
Response 204 No Content Errors

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
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.
Response 201 Created with an empty body. Errors

Revoke a user’s access

DELETE /api/agents/{id}/grants/users/{user_id} 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
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.
Response 201 Created with an empty body. Errors

Remove an allowed agent

DELETE /api/agents/{id}/grants/agents/{target_agent_id} Response 204 No Content. Removing the last entry lifts the allowlist, so the agent may call any agent its user can reach.