Vercel

You can connect a Vercel Pro or Enterprise team to Opal to manage team membership, team roles, and project access. Create one Opal app per Vercel team. A Full Account token can see many teams. Each app is still bound to a single team ID.

​

Supported resources

With Opal’s Vercel integration:

• People can request access to Vercel team roles and project roles through Opal, after you turn on Allow Requests for those resources.
• Admins can review who is on the team, including pending invites, who holds each team role, and who has direct project access. Admins can grant or revoke that access, including in access reviews.
• Admins can invite people onto a Pro team without adding a paid seat. Opal never lets Vercel auto-bill a new seat.

​

Requirements

To connect Vercel, you must first:

• Be an Opal Admin.
• Have a Vercel team on Pro (including Pro Trial) or Enterprise. Hobby teams cannot collaborate, and Opal rejects them when you create the app.
• Have the Vercel integration enabled for your organization. If you do not see Vercel under + App, contact your Opal admin or Opal support.
• Create a Full Account personal access token from a team owner on that team, as described in step 1.

​

1. Create a Full Account personal access token

Signed in as a team owner, open your personal Vercel account settings, not team Settings:

1. Go to Account Tokens: Settings > Tokens.
2. Create a token and set its scope to Full Account. Team-scoped and project-scoped tokens cannot authenticate this app.
3. Copy the token. Vercel shows it once. It typically starts with vcp_.

Full Account is required even though the Opal app manages one team. Opal reads the token holder’s account to confirm who owns the connection. Team-scoped and project-scoped tokens cannot do that.

​

2. Find your team ID

In Vercel, open the team you want Opal to manage:

1. Go to Team Settings > General.
2. Copy the team ID. It looks like team_….

You paste this ID into Opal. Opal does not list your teams for you.

​

3. Add Vercel in Opal

In Opal, go to Inventory > + App, then select Vercel. Fill in the following fields, then create. Opal validates the token, the team, the plan, and that it can list members and projects.

​

4. Turn on provisioning and requests

Open the new app and set both of these. A new app leaves them off:

• Provision Vercel users. Without this, granting access does not send an invite. Opal reports that the person has no account on Vercel.
• Deprovision Vercel users. Without this, you cannot remove someone from the app.

Then import team roles and projects from … > Import items. Imported resources start with Allow Requests off. Open each Vercel Role or Vercel Project you want people to request, and turn Allow Requests on. Only those resources appear in Request Access.

​

What Opal syncs

• Users: Confirmed team members and pending invites, matched by email. Opal records a pending invite with the type Pending invite, and the account ID starts with invite: until they accept. Join requests, where someone asked to join the team, are not synced as users.
• Roles: Vercel Role resources. Each person holds exactly one team role: Owner, Member, Developer, Security, Billing, Pro Viewer, Enterprise Viewer, or Contributor.
• Projects: Vercel Project resources, with direct assignments of Project Administrator, Project Developer, and Project Viewer.

Opal does not sync Access Groups, permission groups, or Vercel events.

​

Inviting people

Adding someone to the Vercel app invites them by email. It does not create an active member immediately. They have 7 days to accept, or 30 days if SAML is enforced. Until they accept:

• Their account ID in Opal starts with invite:.
• Granting the same team role the invite already uses succeeds. On Pro, that role is Pro Viewer, because the invite already includes it.
• Granting Billing stays pending until they accept. After they accept, the next sync applies it. On Pro, a second Billing member is still refused.
• Granting Owner, Member, Developer, Contributor, or Security is refused. The invite still goes out as Pro Viewer.
• Granting a project role to a Pro Viewer invite is refused. That team role cannot hold a project role. A project grant stays pending only when the invite’s team role can hold it, such as Contributor, or Developer with Project Administrator.

On Pro, Opal always invites at Pro Viewer, which does not use a paid seat. If the request was for a paid role, the invite still goes out as Pro Viewer and the paid role is refused. Assign that role in Vercel if you need it. Opal syncs it on the next pull. On Enterprise, Opal does not send new invites. Add the person in Vercel, or in your identity provider, then manage their role in Opal after they appear on the next sync. If someone already requested access in Vercel, a join request, Opal can accept that request. Opal never accepts an unopened invite on the person’s behalf.

​

Team roles

Each user holds one team role, so granting a Vercel Role moves them off their previous role. You can assign users to Vercel Role and Vercel Project resources from those resources in Opal (+ Users), or people can request them after Allow Requests is on. Opal changes a role only when the change cannot add a paid Vercel seat: Opal does not grant or revoke Owner for the token holder, and it does not remove or demote the last team owner.

​

Project access

Vercel only honors project assignments for some team roles: Opal does not change someone’s team role to Contributor to make a project grant succeed. Grant Contributor in Vercel first, if that role uses a paid seat, then grant the project role. Project Guest is not a grantable role. Access Groups are not synced, so a revoke in Opal clears the direct project assignment only. Access that still comes from an Access Group remains.

​

Removing people

Vercel has no deactivate or suspend. Removing someone from the Vercel app deletes the member or revokes the pending invite. Re-entry requires a new invite. Opal removes the app account immediately. Vercel role and project rows in Opal are removed on the next sync. If you add the same person again before that sync, Opal can report that they are already on the resource. Opal will not remove:

• The person whose token authenticates the app
• The last remaining team owner

​

Directory Sync and Enterprise Managed Users

If the team uses Directory Sync or Enterprise Managed Users, treat Opal as read-only for that team. Invite, role change, and remove stay disabled so Opal and the identity provider do not overwrite each other. Manage membership in the identity provider.

​

Token rotation

Tokens can expire. Opal does not warn before expiry. Rotate the token from the app’s credentials when you replace the owner, or when the token is close to expiry.

​

Limitations

The Vercel integration does not support:

• Hobby teams
• Team-scoped or project-scoped tokens
• OAuth, including Sign in with Vercel
• Access Groups and Directory Sync role mappings
• Permission groups
• Managing members across more than one team from a single app
• Automatic paid-seat purchases for Owner, Member, Developer, Contributor, or Security
• Inviting new members on Enterprise teams