> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contentwrap.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Step 1: Connect Your Sanity Project

> Start by linking ContentWrap to your Sanity project using your project ID, dataset name, and API token.

## Before You Begin

You'll need three pieces of information from your Sanity project:

1. **Project ID** - Found in your Sanity dashboard
2. **Dataset name** - Usually `production` or `development`
3. **API Token** - Must have **Editor** permissions

<Card title="Need help finding these?" icon="question-circle" href="/prerequisites#sanity-api-token">
  See prerequisites for detailed instructions
</Card>

## Find Your Sanity Credentials

### Get Your Project ID

<Steps>
  <Step title="Go to sanity.io/manage">
    Navigate to [sanity.io/manage](https://sanity.io/manage)
  </Step>

  <Step title="Select your project">
    Click on the project you want to migrate content into
  </Step>

  <Step title="Copy the Project ID">
    Find the Project ID in the project settings or URL

    Example: `abc123xyz`
  </Step>
</Steps>

### Choose Your Dataset

Your dataset is where content will be imported. Common options:

* **`production`** - Your live, published content
* **`development`** - Test/staging environment
* **`staging`** - Pre-production environment

<Tip>
  **First migration?** Use `development` or `staging` to test the migration safely before importing to `production`.
</Tip>

### Create an API Token

<Steps>
  <Step title="Go to API settings">
    In your Sanity project management console, click **API** in the sidebar
  </Step>

  <Step title="Click 'Add API Token'">
    Create a new token with these settings:

    * **Name**: MigrateKit Migration
    * **Permissions**: **Editor** (required for creating documents)
  </Step>

  <Step title="Copy the token immediately">
    Save it somewhere safe—you won't be able to see it again
  </Step>
</Steps>

## Connect in MigrateKit

### Add Your Sanity Project

If you haven't added a Sanity project yet:

<Steps>
  <Step title="Click 'Add Sanity Project'">
    In your ContentWrap dashboard (app.contentwrap.io), navigate to **Settings** → **Sanity Projects**
  </Step>

  <Step title="Enter your credentials">
    Fill in the form:

    * **Project ID**: Your Sanity project ID
    * **Dataset**: Your dataset name
    * **API Token**: The token you created
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** to verify credentials

    <Check>
      You should see "Connection successful" with your project name
    </Check>
  </Step>

  <Step title="Save the project">
    Click **Save** to store your Sanity project in your account
  </Step>
</Steps>

{/* Code: packages/converter-ui/src/components/QuickConnectWizard.tsx */}

### Select an Existing Project

If you've already connected a Sanity project:

<Steps>
  <Step title="Choose from dropdown">
    Select your project from the **Sanity Project** dropdown
  </Step>

  <Step title="Select dataset">
    Choose which dataset to import into
  </Step>
</Steps>

## Manage Document Types

After connecting a project, define which document types to use for migrations. You can add them manually or sync from your deployed Sanity dataset.

* **Add type manually**: Create a document type entry yourself
* **Sync types from Sanity**: Pull existing document types from your deployed dataset (recommended if schemas are already deployed)
* Shows counts per type (documents detected) and schema status

{/* Code: packages/converter-ui/src/components/DocumentTypeManager.tsx */}

## Manage Schema Fields

For each document type, set up schema fields before mapping CSV columns. You can add fields manually or sync from Sanity.

* **Sync fields from Sanity**: Pull field definitions from deployed schema
* **Add field manually**: Define Sanity field name and type yourself
* MigrateKit attempts to infer types from existing values; you can override any field type

{/* Code: packages/converter-ui/src/components/SchemaExplorer.tsx */}

## Troubleshooting Connection Issues

<AccordionGroup>
  <Accordion title="'Invalid API token' error">
    **Causes:**

    * Token was copied incorrectly (extra spaces/characters)
    * Token doesn't have Editor permissions
    * Token was revoked or deleted

    **Fix:**

    * Create a new token with Editor permissions
    * Copy the entire token without extra spaces
    * Make sure you're using the correct project
  </Accordion>

  <Accordion title="'Project not found' error">
    **Causes:**

    * Project ID is incorrect
    * Typing error in Project ID
    * Using project name instead of ID

    **Fix:**

    * Double-check Project ID in your Sanity dashboard
    * Copy-paste instead of typing manually
    * Project ID is alphanumeric (e.g., `abc123xyz`), not the project name
  </Accordion>

  <Accordion title="'Dataset not found' error">
    **Causes:**

    * Dataset name is misspelled
    * Dataset doesn't exist in this project
    * Capitalization is wrong

    **Fix:**

    * Verify dataset name in Sanity project settings
    * Dataset names are case-sensitive
    * Create the dataset in Sanity if it doesn't exist
  </Accordion>

  <Accordion title="'Insufficient permissions' error">
    **Cause:** API token doesn't have Editor permissions

    **Fix:**

    * Create a new token with **Editor** role
    * Delete the old token for security
    * Update the token in your dashboard
  </Accordion>
</AccordionGroup>

## Security & Best Practices

### Protect Your API Token

* **Never commit tokens to git** - Add to `.gitignore`
* **Don't share publicly** - Treat like a password
* **Revoke unused tokens** - Delete tokens you're not using
* **Use environment variables** - For automation/scripts

### Token Management

* **Create project-specific tokens** - One per project/tool
* **Name tokens clearly** - E.g., "MigrateKit Migration - Production"
* **Rotate periodically** - Create new tokens, revoke old ones
* **Revoke if compromised** - Immediately delete and create new

### Multiple Projects

You can connect multiple Sanity projects to your ContentWrap account:

* Each project saved separately
* Switch between projects during migration
* Test in development, import to production