Skip to content
Docs

Sandbox Authentication

The Sandbox SDK supports two authentication methods: Vercel OIDC tokens (recommended) and access tokens.

Vercel OIDC token (recommended)

The SDK uses Vercel OpenID Connect (OIDC) tokens when available.

Local development: Download a development token by connecting to a Vercel project:

vercel link
vercel env pull

This creates a .env.local file with a VERCEL_OIDC_TOKEN. The token expires after 12 hours, so run vercel env pull again if you see authentication errors.

Production: Vercel manages token expiration automatically when your code runs on Vercel.

Access tokens

Use access tokens when VERCEL_OIDC_TOKEN is unavailable, such as in external CI/CD systems or non-Vercel environments.

You need:

Set these as environment variables:

VERCEL_TEAM_ID=team_xxx
VERCEL_PROJECT_ID=prj_xxx
VERCEL_TOKEN=your_access_token

Then pass them to Sandbox.create():

import { Sandbox } from '@vercel/sandbox';
 
const sandbox = await Sandbox.create({
  teamId: process.env.VERCEL_TEAM_ID!,
  projectId: process.env.VERCEL_PROJECT_ID!,
  token: process.env.VERCEL_TOKEN!,
});
import asyncio
import os
 
from vercel import sandbox
from vercel.api import session
from vercel.sandbox import SandboxCredentials, SandboxServiceOptions
 
 
async def resolve_credentials() -> SandboxCredentials:
    return SandboxCredentials(
        token=os.environ["CI_VERCEL_TOKEN"],
        project_id=os.environ["CI_VERCEL_PROJECT_ID"],
        team_id=os.environ["CI_VERCEL_TEAM_ID"],
    )
 
 
async def main() -> None:
    sandbox_options = SandboxServiceOptions(
        credentials_factory=resolve_credentials,
    )
 
    async with session(service_options=[sandbox_options]):
        async with sandbox.create_sandbox() as box:
            print(box.name)
 
 
asyncio.run(main())

For async operations, import AsyncSandbox instead of Sandbox and use await with all methods.

Which method to use

ScenarioRecommended method
Local developmentOIDC token via vercel env pull
Deployed on VercelOIDC token (automatic)
External CI/CDAccess token
Non-Vercel hostingAccess token
Last updated August 25, 2026
Previous
Concepts
Next
Persistence

Was this helpful?