Form Manager With Teams And Permissions

Form.io separates access control into two distinct systems that serve different purposes. Teams control who can access the Developer Portal to build and manage forms. Roles and Permissions control who can interact with forms and submission data within your deployed applications. Understanding this separation prevents configuration mistakes that either lock out legitimate users or expose data to unauthorized access.

Teams are about platform administration. Roles are about application-level authorization. Both systems operate independently, and both require explicit configuration to function correctly.

Teams: Platform-Level Collaboration

Teams exist at the Form.io Portal level, outside any individual project. When you create a team, you are assembling a group of Form.io users who need access to build, view, or manage forms within your projects. Team membership does not automatically grant any permissions. Teams must be explicitly assigned to projects with a specific permission level.

The portal recognizes four team permission levels for projects:

Access grants visibility to a project without functional permissions. Users with Access can see the project exists but cannot read forms or data. This level exists specifically to enable Stage-level permissions, which require a project-level team assignment first.

Read allows team members to view forms and submission data but not modify anything. This suits QA teams, auditors, or stakeholders who need visibility without edit capabilities.

Write permits reading and modifying forms and submissions across the project. Team members can build forms, edit existing ones, and manage submission data. They cannot access project settings or sensitive configuration data.

Admin provides full project control including settings, integrations, and sensitive configuration. Admin-level team members can do everything except delete the project itself, which remains restricted to the project owner.

Project Teams vs Stage Teams

Form.io projects contain Stages that represent different environments (development, staging, production). Teams can be assigned at either the project level or the stage level, with different implications.

Project-level teams receive their assigned permissions across all stages. If you assign a team with Write permissions at the project level, those team members can modify forms in development, staging, and production stages.

Stage-level teams receive permissions only for their designated stage. This enables workflows where developers have Write access to the development stage but no access to production, while operations teams have the inverse configuration.

The hierarchy matters: project-level permissions always override stage-level permissions for the same team. If Team A has Admin at the project level and Read at a specific stage, the Admin permission wins everywhere. Stage teams work only when the same team has Access (not Read, Write, or Admin) at the project level.

This architecture supports standard deployment workflows. Create a “Developers” team with Write access to your Development stage. Create an “Operations” team with Write access to your Production stage. Each group works in their environment without risking changes to the other.

Creating and Managing Teams

Teams are created from the Teams tab in the main portal interface, outside any project context. The user who creates a team becomes its owner. Team owners can add members, remove members, promote members to Team Admin, and delete the team.

Adding team members requires their Form.io email address. For self-hosted deployments, users must exist in the Portal Base project’s User Resource. For the SaaS platform, users must have registered accounts. Team invitations do not send emails. Invited users see pending invitations when they log into the portal and must explicitly accept them.

SSO Teams provide an alternative for organizations using SAML authentication. When creating a team, check the SSO Team option and name the team to match your SSO provider’s role. Users authenticating via SSO with that role automatically join the corresponding Form.io team without explicit invitation or acceptance.

Roles: Application-Level Authorization

While Teams govern portal access, Roles govern what authenticated users can do within your deployed applications. Roles are project-specific. Each project maintains its own set of roles, and roles from one project cannot grant permissions in another project.

Every project includes four default roles:

Anonymous represents unauthenticated users. This role cannot be deleted. Use it to configure permissions for public-facing forms where users are not logged in, such as contact forms or registration pages.

Everyone is a virtual role that matches all users regardless of their actual role assignment. When you assign a permission to Everyone, all other roles inherit that permission. This role cannot be deleted and has a fixed ID of all zeros.

Authenticated and Administrator are starter roles with no inherent special behavior. They exist as placeholders for common permission patterns. You can modify, rename, or delete these roles as needed.

You can create unlimited additional roles to match your application’s authorization model. Each role receives a unique MongoDB ID that identifies it in form configurations and user records.

Permission Scopes

Form.io organizes permissions into three scopes that govern different aspects of the platform:

Project Scope controls access to the project’s API and administrative functions. These permissions determine whether users can list all forms in a project, update project settings, or create new forms programmatically.

Form Scope controls access to form definitions. These permissions determine whether users can view a form’s JSON schema, modify the form structure, or delete the form entirely.

Submission Scope controls access to submission data. These permissions determine whether users can create submissions, read existing submissions, update submissions, or delete them.

Each scope has its own set of permissions configured independently. A user might have permission to view a form (Form Scope: Read) without permission to submit it (Submission Scope: no Create).

Permission Types

Each scope supports eight permission types organized in pairs:

Create Own / Create All: Create Own assigns the creating user as the submission owner. Create All allows creating submissions and assigning ownership to other users.

Read Own / Read All: Read Own permits viewing only submissions you own. Read All permits viewing all submissions regardless of owner.

Update Own / Update All: Update Own permits editing only your submissions. Update All permits editing any submission and changing ownership.

Delete Own / Delete All: Delete Own permits deleting only your submissions. Delete All permits deleting any submission.

The “Own” variants support multi-tenant patterns where users see only their data. The “All” variants support administrative patterns where privileged users manage everyone’s data.

Configuring Form Permissions

Each form has an Access tab where you configure both Form Definition Access (who can view/edit the form schema) and Submission Data Permissions (who can create/read/update/delete submissions).

The most common mistake is forgetting that submission access is disabled by default. Creating a form and embedding it in your application does not automatically allow anyone to submit it. You must explicitly grant Create Own or Create All submission permissions to at least one role (typically Anonymous for public forms or Authenticated for logged-in users).

Similarly, form definition read access is required for users to view the form. Without Read Form Definition permission for the appropriate role, users attempting to load the form receive an authorization error.

A typical configuration for a logged-in user form:

  • Form Definition: Read for Authenticated and Administrator
  • Submissions: Create Own and Read Own for Authenticated, Read All and Update All for Administrator

A typical configuration for a public form:

  • Form Definition: Read for Anonymous
  • Submissions: Create Own for Anonymous (users can submit but not view submissions)

Field-Based Resource Access

Standard role-based permissions work at the form level. Every user with Read All submission access sees all submissions. Field-Based Resource Access provides finer granularity by granting permissions based on field values within submissions.

Consider a medical application where patients are assigned to physicians. You want physicians to see only their assigned patients’ submissions, not all submissions. Field-Based Resource Access achieves this by checking a Resource reference field (the assigned physician) against the currently authenticated user.

Configure Field-Based Resource Access in the form’s Access tab under the Field-Based Resource Access section. You select a Resource reference field from your form and assign permissions that apply when the authenticated user matches that reference.

This creates dynamic permissions: Physician A sees Patient A’s data, Physician B sees Patient B’s data, neither sees the other’s patients. The permission check happens at query time, so no code changes are needed as assignments change.

Group Permissions

Group Permissions extend Field-Based Resource Access for scenarios where users belong to organizational units rather than having direct relationships. Instead of assigning individual users to submissions, you assign groups, and all group members receive access.

The pattern requires three Resources: a Group Resource (departments, teams, classes), a User Resource, and a Join Resource that creates relationships between groups and users. A Group Assignment action on the Join Resource establishes the many-to-many relationship.

Forms then reference the Group Resource through a Select component. Field-Based Resource Access checks whether the authenticated user belongs to the group referenced in each submission. Sales team members see sales submissions, support team members see support submissions.

Group Permissions support optional role differentiation within groups. A user might be an Admin within the Sales group but a Member within the Support group, with different permissions in each context.

Authentication Integration

Roles must be assigned to users through an authentication process. Form.io supports multiple authentication methods that all ultimately produce a JWT token containing the user’s role assignments.

The Login action validates credentials against a User Resource and issues a token with the user’s roles. The Role Assignment action adds or removes roles based on submission events, enabling workflows where completing certain forms grants additional permissions.

OAuth and SAML integrations exchange external identity provider tokens for Form.io JWT tokens. During this exchange, external roles or group memberships can be mapped to Form.io roles, maintaining consistency between your identity provider and Form.io’s permission system.

When Permissions Block Legitimate Actions

If users cannot perform actions they should be able to perform, check these common issues:

Form not visible: The user’s role lacks Read Form Definition permission. Add the role to the Form Definition Access section.

Cannot submit form: The user’s role lacks Create Own or Create All submission permission. Add the role to Submission Data Permissions.

Cannot see submissions: The user’s role lacks Read Own or Read All submission permission, or they are not the submission owner and only have Read Own.

Cannot access project API: The user’s role lacks Project-level Read All permission. Add the role in the project’s Access tab.

Team member cannot see project: The team is assigned with Access permission only, and no stage-level permission is configured. Either upgrade the project-level permission or add stage-level permissions.

Security Considerations

Form.io’s permission system defaults to restrictive access. Submission access is disabled by default. Project settings are protected even from users with project-level permissions. Only project owners can delete projects.

Roles are sandboxed to projects. A role ID from Project A cannot be used to access resources in Project B, even if someone manually crafts a token with that role.

For compliance scenarios requiring audit trails, the Security Module includes audit logging that records all access and modification events. This complements permissions by providing visibility into who did what, while permissions control who can do what.

Multi-tenant deployments provide additional isolation. Each tenant operates in its own project context with independent roles, permissions, and data. Tenant A’s administrators have no visibility into Tenant B’s forms or submissions.

Related Resources