# Vercel access token

URL: https://ship-and-scale.vercel.app/docs/accounts/vercel

Save your Vercel token and connect GitHub for Deployment Kickstart.

By the end of this guide, your Vercel token will be saved in the starter's root `.env` file and GitHub will be connected for deployment. Kickstart creates the Vercel project and configures hosting for you.

You only need Vercel when you're ready to deploy. Finish the first Kickstart and prepare your [GitHub access token](/docs/accounts/github) before continuing.

## Create and save the token [#create-and-save-the-token]

### Create or sign in to your account [#create-or-sign-in-to-your-account]

Open [Vercel](https://vercel.com) and sign up or sign in. Use the team that will own your app, with permission to create projects and deployments.

The free [Hobby plan](https://vercel.com/docs/plans/hobby) works for building and testing your deployment. It's limited to personal, non-commercial projects, so upgrade to [Pro](https://vercel.com/pricing) before your app takes payments.

### Generate an access token [#generate-an-access-token]

Open [Account Tokens](https://vercel.com/account/tokens). This is under your personal account's **Settings → Tokens**, even when the app belongs to a team. The **Create Token** form appears on this page.

<figure className="docs-setup-shot">
  <a href="/docs-assets/images/accounts-vercel-tokens-page.png" target="_blank" rel="noreferrer" title="Open screenshot at full size">
    <img alt="Vercel account settings with Tokens selected in the sidebar and the Create Token form visible." src="/docs-assets/images/accounts-vercel-tokens-page.png" width="1370" height="474" />
  </a>

  <figcaption>
    Vercel · Account settings → Tokens.
  </figcaption>
</figure>

1. Under **Token Name**, enter `Ship & Scale Kickstart`.
2. Under **Scope**, select the team that will own your app. You don't need **Full Account** access.
3. Under **Expiration**, choose **90 days**. That covers deployment and any retries. Choose **No Expiration** only if a coding agent will keep using this token for Vercel changes, and revoke it when you no longer need it.
4. Click **Create** and copy the token immediately. Vercel only shows its full value once.

The token must be scoped to the team that owns this project. Keep `VERCEL_TEAM_ID` and `VERCEL_PROJECT_ID` matched to the team and project saved during deployment. For a new project, leave the project ID blank until Kickstart records it; for later checks and secret updates, use the recorded project rather than a similarly named project.

<figure className="docs-setup-shot">
  <a href="/docs-assets/images/accounts-vercel-create-token.png" target="_blank" rel="noreferrer" title="Open screenshot at full size">
    <img alt="Vercel Create Token form with Ship & Scale Kickstart as the name and No Expiration selected. Scope still needs your team selection." src="/docs-assets/images/accounts-vercel-create-token.png" width="930" height="325" />
  </a>

  <figcaption>
    Enter a name, select your own team in Scope, choose an expiration, then click Create. The example shows No Expiration.
  </figcaption>
</figure>

### Save it in `.env` [#save-it-in-env]

Open the root `.env` file beside `package.json`. Keep the settings from your local installation. Find the existing `VERCEL_TOKEN=` line, paste the token after the equals sign and save:

```dotenv title="Your private .env"
VERCEL_TOKEN=replace_with_your_vercel_token
```

Replace the example with your real token and keep one active `VERCEL_TOKEN` line. For a new deployment, leave `VERCEL_TEAM_ID`, `VERCEL_PROJECT_NAME`, `VERCEL_PROJECT_ID` and `APP_URL_LIVE` blank. Kickstart fills them in.

**Keep the token private**

This token can manage resources in its selected scope until it expires or you revoke it. Keep it only in your local `.env`. Don't import your whole `.env` into Vercel; Kickstart uploads only the runtime values your app needs.

## Connect GitHub [#connect-github]

Vercel also needs its own connection to GitHub to read your app's code. Saving the two tokens does not create this connection.

### Link your GitHub account [#link-your-github-account]

Open Vercel's [Authentication settings](https://vercel.com/account/settings/authentication). Under **Sign-in Methods**, connect **GitHub** using the same account as your GitHub token. If your GitHub username is already shown, this step is done.

<figure className="docs-setup-shot">
  <a href="/docs-assets/images/accounts-vercel-github-connection.png" target="_blank" rel="noreferrer" title="Open screenshot at full size">
    <img alt="GitHub row in Vercel Sign-in Methods showing an already connected GitHub username." src="/docs-assets/images/accounts-vercel-github-connection.png" width="868" height="116" />
  </a>

  <figcaption>
    Vercel · Authentication → Sign-in Methods. Your own GitHub username should appear here.
  </figcaption>
</figure>

### Allow access to your app's repository [#allow-access-to-your-apps-repository]

Open the [Vercel GitHub App](https://github.com/apps/vercel/installations/new). Choose the account that will own your app's repository. For the automatic Kickstart setup, this is your personal GitHub account.

Kickstart creates your app's repository later, so it doesn't exist yet. Choose one of these:

* **All repositories** is the simplest path. Vercel can read the new repository as soon as Kickstart creates it. It also gives Vercel access to every current and future repository owned by that account.
* **Only select repositories** keeps access narrower. GitHub requires at least one repository here, so select any existing one for now. When Kickstart creates your app's repository, it pauses with a link; add the new repository there and rerun the same command.

<figure className="docs-setup-shot docs-setup-shot-compact">
  <a href="/docs-assets/images/accounts-vercel-github-repositories.png" target="_blank" rel="noreferrer" title="Open screenshot at full size">
    <img alt="Vercel GitHub App repository permissions with Only select repositories selected and the Select repositories control visible." src="/docs-assets/images/accounts-vercel-github-repositories.png" width="504" height="420" />
  </a>

  <figcaption>
    GitHub · Vercel App → repository access. Use Select repositories to choose which code Vercel can read.
  </figcaption>
</figure>

Review the permissions and click **Install** for a new installation or **Save** when updating one. If GitHub shows **Request**, an organization owner must approve it before you continue.

If Kickstart later pauses for repository access, keep the generated `.env` values and `.kickstart` files so the rerun continues with the same resources.

## You are finished when [#you-are-finished-when]

* `VERCEL_TOKEN` has one saved value in your root `.env`.
* Its scope matches the Vercel team that will host your app.
* GitHub is connected to Vercel, and the Vercel App is installed for your repository owner.

Once the other [deployment prerequisites](/docs/start/deployment-kickstart#finish-local-setup-first) are ready, run:

```sh
npm run kickstart:deploy -- --check
```

This checks access without creating provider resources. Access to a new repository is checked after Kickstart creates it during deployment.

**If your team, token or repository is unavailable**

If your team is missing from **Scope**, check that you're signed in to the right Vercel account and have access to that team. The token cannot grant permissions your account doesn't have. See [Vercel's token guide](https://vercel.com/kb/guide/how-do-i-use-a-vercel-api-access-token).

If the token expires or is revoked, create a replacement for the same team and update `VERCEL_TOKEN`. Keep the generated project IDs and receipts.

If Vercel cannot find the repository, check the GitHub connection, App installation owner and selected repositories. Follow [Vercel's repository access guide](https://vercel.com/kb/guide/unable-to-find-github-repository) if it is still missing.

[Back to Accounts](/docs/accounts)

Check the remaining deployment accounts, then deploy.