Connect Vercel

CoIsland calls Vercel’s REST API straight from your Mac: there is no CoIsland server and no CoIsland account. The token stays in your login Keychain, and every request the Vercel connector sends is a GET. Vercel tokens have no read-only setting, so a token can do whatever its scope reaches; keep the scope as narrow as what you watch.

Create a Vercel access token

1. In the Vercel dashboard, make sure the scope selector at the top left shows your personal account, then open Account Settings › Tokens (vercel.com/account/tokens).
2. Token name: one you will recognize, such as CoIsland.
3. Scope: the narrowest one that covers what you will watch (see the table below).
4. Expiration: pick one, then Create. CoIsland’s Test connector shows the expiry, and every monitor card warns in its last week.
5. Copy the token. It starts with vcp_ and Vercel shows it only once.

Scope	What CoIsland can watch	team: in a monitor
Full Account	Your own projects and every team you belong to	Optional: without it, your default team
A team, All Projects	Every project of that team	Leave it out: Vercel infers the team
A team, then one project	That project only	Leave it out; name only that project

A project-scoped token cannot read your user or your teams, so Test connector says “Project-scoped token” and names its project, and the Team menu in the editors falls back to a text field.

When your team blocks the token

• Two-factor authentication enforced: a team can require 2FA, and then tokens of members without it stop working. CoIsland says “The team requires two-factor authentication; enable it on your Vercel account.” Enable 2FA, then create the token again.
• SAML single sign-on enforced (Enterprise, or Pro with the SAML add-on): the team only accepts a token created after signing in through its identity provider. CoIsland says “The team requires SAML single sign-on: sign in to Vercel through SSO, then create the token again.”
• A team owner cannot edit or delete your personal token, and there is no approval step: a token scoped to your own Hobby team always works.

Connect Vercel in CoIsland

1. Open Settings › Connectors and click + (Add Connector).
2. Choose Vercel, fill in the two fields, then click Test connector.
3. Click Add Connector.

Field	What to enter
Connector name	What monitors call it: letters, digits, _ and -, starting with a letter. CoIsland suggests vercel
Access token	The token you copied, with no spaces or line breaks

Test connector calls GET /v5/user/tokens/current and GET /v2/user and saves nothing. It shows your username and email, the token’s scope, its expiry (or that it never expires), and a warning when Vercel has marked the token as leaked.

Add Connector keeps the connector’s name in ~/Library/Application Support/CoIsland/connectors.json and the token in your login Keychain, never in a file.

Watch Vercel: the three monitor kinds

Open Settings › Monitors, click + (New Monitor) and choose Vercel. Every editor has fields for the team (from your token’s teams) and the projects (searched on Vercel as you type), writes the query under them, and has a Test button that runs it once.

Kind	What alerts	What CoIsland calls
Deployments	A deployment of the last 7 days enters a state you picked: failed unless you choose canceled, ready, blocked and others	GET /v7/deployments, per project, following its pages
Stuck builds	A deployment queued or building for longer than you allow (20 minutes unless you choose, from 5 minutes to 12 hours)	The same list, for the last day
Domain problems	A project domain not pointing at Vercel, not verified, or, when you ask, whose certificate expires within a number of days	GET /v9/projects/{project}/domains, GET /v6/domains/{domain}/config, and GET /v8/certs when certificates are asked for

team:acme project:web target:production
project:web state:error,canceled branch:main checks:failed
team:acme target:preview for:30m
project:web problem:misconfigured cert:14d

• target:preview keeps the deployments that have no production target, as Vercel lists previews.
• checks:failed keeps deployments whose checks concluded failed.
• A redeploy is a new deployment, so a build that fails again alerts again. A fixed domain leaves the result, and breaking it again alerts again.
• A result bigger than 10 pages of 100 deployments compares nothing: narrow the projects or the states.

Clicking a row in the notch opens the alert in CoIsland. There, a failed build shows its error, the failing step and the last lines of its build log; a misconfigured domain shows the DNS record to add. Open in Vercel goes to the deployment’s inspector or the project’s domain settings.

A Vercel monitor is a watch file like any other; its -- kind: is vercel.deployments, vercel.stuck or vercel.domains. Watch files lists every header key.

Troubleshooting Vercel connector errors

• “The token was refused. Check it has not expired or been revoked. Create a new one at vercel.com/account/tokens.” Vercel answers a wrong, expired or revoked token with 403 invalidToken.
• “project web: not allowed. The token’s scope may not include it, or you left the team.” The token’s scope does not reach that team or project, or a project-scoped token was asked about another project.
• “project web: Not found, or not visible to this token.” The project was renamed or deleted, or the team named is not the one it belongs to.
• “Rate limited; retry after 14:05.” Vercel allows 1,000 deployment lists a minute; CoIsland waits, then retries.
• “Token expires in 3 days: create a new one at vercel.com/account/tokens.” Shown on every card of that connector during the token’s last week.

Frequently asked questions

Can CoIsland change anything on Vercel?

No. The connector only sends GET requests: it never redeploys, promotes, cancels or edits a domain.

Does it work on the free Hobby plan?

Yes. Deployments, stuck builds and domain problems all work on Hobby.

Why is there no DDoS or firewall monitor?

Vercel’s attack status endpoint is not documented as available on every plan, and CoIsland could not verify it. It is planned for a later version.