How to Get a Vercel API Token for CI
Create a Vercel API token in 5 steps, scoped to one team with an expiration for CI. Ringtail mints the scoped token from Vercel's official API, value-free.
Rocco made the CI token, scoped it to one team, set it to expire, and left before anyone noticed.
🦝 Rocco: ci doesn't need a token that lives forever. give it 90 days and one team.
To get a Vercel API token, sign in at vercel.com, open Account Settings → Tokens, click Create Token, name it, set the Scope to the specific team (not your whole account), choose an Expiration, and copy the value once — Vercel shows it a single time. Use that token in CI as VERCEL_TOKEN. Below is the full flow, the scope choices that keep a CI token safe, and how Ringtail mints the token from Vercel's official API without exposing it to your coding agent.
Where do you create a Vercel API token?
You create it in your personal Account Settings → Tokens, reached from the avatar menu at vercel.com → Settings → Tokens. Vercel tokens are account-level credentials tied to you, but each one can be scoped to a single team, which is what you want for CI so the token can only touch that team's projects.
Every token is listed on that page with its name, scope, expiration, and last-used date — your audit trail. Name tokens for where they run (github-actions-acme-ci) so a leaked one is instantly traceable to a pipeline you can rotate.
What are the steps to create the token?
Five steps:
- Open Account Settings → Tokens.
- Click Create Token and give it a descriptive, pipeline-specific name.
- Set Scope to the specific team the CI job deploys to — not "Full Account."
- Choose an Expiration (Vercel offers preset windows). Pick the shortest that outlives your rotation cadence.
- Click Create Token, then copy the value immediately — Vercel displays it once and never again.
Store it as a CI secret named VERCEL_TOKEN, never committed to the repo. If you're wiring GitHub Actions, that's a repository or environment secret — the same "keep it out of git" discipline in stop committing secrets to git.
How do you scope a Vercel token for CI?
Scope it to one team with a short expiration — those two choices carry most of the safety. Vercel tokens can't be permission-limited the way a Cloudflare token can, so the two levers you have are:
- Team scope: bind the token to the single team whose projects CI deploys. A leaked team-scoped token can't reach your other teams' projects.
- Expiration: set a finite window so a token that escapes into a CI log dies on its own. This turns rotation from a chore into a default.
Because a Vercel token is broader than a per-resource key, treat it like a deploy credential: one per pipeline, short-lived, rotated on a schedule. The reasoning is the same as rotating API keys without breaking production — short-lived credentials make rotation routine instead of risky.
🦝 Rocco: one team, one expiry, one pipeline. a ci token that outlives the project is just a liability with a login.
How do you use the token in CI?
Read it from the CI secret and pass it to the Vercel CLI — never inline it in a workflow file:
npm install --global vercel
vercel pull --yes --environment=production --token=$VERCEL_TOKEN
vercel build --prod --token=$VERCEL_TOKEN
vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN
In GitHub Actions, VERCEL_TOKEN comes from secrets.VERCEL_TOKEN; the CLI reads --token or the VERCEL_TOKEN environment variable. A 403 from the CLI means the token's team scope doesn't include the project you're deploying — which is the scope working.
How does Ringtail create the token for you?
Once you've connected your Vercel account to Ringtail one time, Ringtail mints the CI token for you by driving Vercel's official API — you never open the Tokens page for a new pipeline again. Ringtail reads VERCEL_TOKEN from your .env.example, calls Vercel's official API to create a token scoped to the right team, confirms it can list that team's projects, and writes the value into .env.local and your Infisical — where your CI pulls it.
It's value-free: the token is returned by Vercel's API straight into your files. Your coding agent decides which team to scope to, but never sees the secret string — the model handles names and scopes, not the credential. Install it once:
curl -fsSL ringtail.sh | sh
ringtail up
Ringtail uses official provider APIs only — never a browser bot with your Vercel login. Vercel's token API is first-class, so after the one-time connection the flow is zero-touch. For the full pattern across every provider in a project, see how to stop juggling 15 API keys on every new project.
FAQ
Where do I create a Vercel API token?
Sign in at vercel.com, open the avatar menu → Settings → Tokens (your personal Account Settings), and click Create Token. Give it a name, set the Scope to a specific team, choose an Expiration, and copy the value — Vercel shows the full token only once at creation. After that the page lists the name, scope, and last-used date but never the secret again.
How do I scope a Vercel token so CI can only touch one project's team?
When creating the token, set its Scope to the specific team that owns the project, rather than "Full Account." Vercel tokens are scoped by team rather than by individual permission, so a team-scoped token can deploy that team's projects but can't reach your other teams. Pair it with a short expiration to limit exposure if the token leaks into a CI log.
How do I use a Vercel token in GitHub Actions?
Store the token as a repository or environment secret named VERCEL_TOKEN, then pass it to the Vercel CLI with --token=$VERCEL_TOKEN (or let the CLI read the VERCEL_TOKEN environment variable). Typical steps are vercel pull, vercel build --prod, and vercel deploy --prebuilt --prod, each with the token. Never hardcode the token in the workflow YAML.
Can Ringtail mint a Vercel CI token for me?
Yes. After you connect your Vercel account to Ringtail once, Ringtail calls Vercel's official API to create a team-scoped token for each pipeline, validates it, and writes it to .env.local and Infisical — value-free, so the token never reaches your coding agent. It uses the official API only, never browser automation.