How to Manage Fast.io Workspace Permissions API

What Is the Fast.io Workspace Permission Management API?

The Fast.io Permission Management API enables strict role-based access control, ensuring AI agents only access authorized files.

It supports granular permissions across four levels: organization, workspace, folder, and file. Core permission levels and their programmatic identifiers are:

These roles apply via member management endpoints for orgs, workspaces, and shares. Permissions inherit down the hierarchy unless overridden.

Permission Hierarchy and Inheritance

Permissions follow a clear hierarchy in Fast.io.

Organization-level roles control access to all workspaces. Workspace roles override org for that workspace. Folder and file permissions allow fine-grained overrides.

For example, an "editor" at workspace level can edit all files unless a folder grants only "viewer". This setup supports complex agent teams where different agents handle different tasks.

How to Add Members and Set Roles via API

Use POST /{entity_type}/{entity_id}/members/ to add users or agents.

curl example (add editor to workspace):

curl -X POST https://api.fast.io/current/workspaces/{workspace_id}/members/ \\
  -H "Authorization: Bearer {token}" \\
  -d "user_id={user_or_agent_id}&role=editor"

Replace {entity_type} with "orgs", "workspaces", or "shares". Common roles: viewer, editor, agent, owner.

Node.js example:

const response = await fetch(`https://api.fast.io/current/workspaces/${wsId}/members/`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    user_id: agentId,
    role: 'agent'
  })
});

List members with GET /{entity_type}/{entity_id}/members/.

Granular Folder and File Permissions

Beyond member roles, set ACLs on folders/files for non-member access.

Use storage endpoints to set permissions on nodes.

Example: Restrict folder to editors only:

POST /workspaces/{ws_id}/storage/{folder_id}/acl/ with rules array defining user_id/role.

Inheritance: Child nodes inherit unless explicit ACL set. Agents benefit from file locks alongside permissions for concurrent safety.

Best Practices for Agent Permission Scoping

Competitors overlook agent-specific scoping. Follow these:

• Use "agent" role for API-only access, avoiding UI clutter.
• Scope to folders for task isolation: analysis agent gets /data/, delivery agent /output/.
• Combine with webhooks for reactive workflows: notify on permission changes.
• Audit via events/search/ filtered by "permission_change".

For multi-agent: owner creates, delegates editor/agent roles, monitors via activity logs.

Troubleshooting Permission Issues

Common errors:

• 1680 APP_DENIED: Insufficient role.
• Check token scopes with /user/.
• List effective permissions via /members/{id}/effective/.

Test with curl, verify inheritance.