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 inAuthorization: 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.
409:
Get an access summary
GET /api/agents/{id}/grants
Everything about the agent’s access in one call.
200 OK
Get visibility
GET /api/agents/{id}/visibility
Only the public flag.
Response 200 OK
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.
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.
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.
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.
Related
- User → agent access
- Access control reference
- MCP gateway for connector grants, which use a similar shape under
/api/mcp/connectors/{id}/grants