Managing User Permissions

This guide explains how to manage user permissions with the Frame.io V4 API. It covers how permissions work at the Account, Workspace, and Project levels, and which endpoints to use at each.

Permission Levels

Permissions in Frame.io are managed across the Account, Workspace, and Project levels. Each level uses its own set of roles:

Account 
│
├── (admin)  - full access to all Workspaces, Projects, and Restricted Projects
│
└── (member)
        │
        ├── Workspace - (full_access | editor | edit_only | commenter | viewer)
        │       │
        │       └── Project - (full_access | editor | edit_only | commenter | viewer)
        │
        └── Restricted Project - (members require direct invite)

Every user has an account role. Through the API, you can set a user’s role to admin or member. Account Admins have full access to all Workspaces and Projects. Account Members can be selectively added to the Workspaces and Projects they need.

When you add an Account Member to a Workspace, the permission level you assign (full_access, editor, edit_only, commenter, or viewer) applies to all existing and future Projects within it. For example, if you add an Account Member as a viewer, they will have viewer permissions whenever they access any Project in that Workspace.

That same Account Member can be added to a specific Project within that Workspace as an editor. As a result, whenever they access that Project they will have editor permissions. Their viewer permissions continue to apply for all other Projects in that Workspace.

Since Project assignments are separate from Workspace assignments, if you remove that Account Member from the Workspace, they will retain their editor permissions for that single Project.

Restricted Projects are the exception. Account Members always require a direct invite. More on this in the Project Level Permissions section below.

Account Level Permissions

Every user in your Account has a role:

Account Admins have full access everywhere. To limit an Admin’s access to specific resources, first change their account role to Member, then add them to the Workspaces or Projects they need.

For example:

1
curl https://api.frame.io/v4/accounts/:account_id/users \
2
     -H "Authorization: Bearer <token>"

1
curl -X PATCH https://api.frame.io/v4/accounts/:account_id/users/:user_id \
2
 -H "Authorization: Bearer <token>" \
3
 -H "Content-Type: application/json" \
4
 -d '{
5
"data": {
6
"role": "member"
7
}
8
}'

1
curl -X PATCH https://api.frame.io/v4/accounts/:account_id/projects/:project_id/users/:user_id \
2
  -H "Authorization: Bearer <token>" \
3
  -H "Content-Type: application/json" \
4
  -d '{
5
"data": {
6
 "role": "edit_only"
7
}
8
}'

Account Permissions Endpoints

Workspace Level Permissions

When you add an Account Member to a Workspace, they have that permission level on all Projects within it. Workspaces are invite-only, so Account Members only see the Workspaces they are added to.

Workspace Permissions Endpoints

Project Level Permissions

Projects use the same permission levels as Workspaces. Add a user directly to a Project when they need access to that specific Project only, or when they need a different permission level than their Workspace assignment. Users do not need Workspace access to be added to a Project.

Example: Add a user to a Project

1
curl -X PATCH https://api.frame.io/v4/accounts/:account_id/projects/:project_id/users/:user_id \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "data": {
6
    "role": "full_access"
7
  }
8
}'

Restricted Projects

Restricted Projects require a direct invite. Workspace access does not carry over, so users can only access a Restricted Project if they have been added to it directly.

To grant a Member access, add them to the Project with the appropriate permission level.

Project Permissions Endpoints

Resources

Additional resources you may find helpful:

• The Frame.io Developer Forum is where developers can ask questions, share feedback, and discuss what they’re building
• Help Center article on User Roles and Permissions
• The OWASP Authorization Cheat Sheet, for additional information on Relationship and Attribute based access control