Auth tokens

In the TypeScript SDK, auth tokens are the short-lived credentials that CSVImporter uses to keep the importer authenticated in the browser without exposing your long-lived secret key.

authToken is not the same as sessionId. The SDK generates a sessionId when the importer opens and uses it to group chunks, callbacks, and staging rows. The auth token only proves the browser is allowed to talk to ExpressCSV and may rotate during a long import.

Implement getAuthToken() so it returns a fresh token from your backend:

const importer = new CSVImporter({
  schema,
  getAuthToken: async () => {
    // Ask your backend for a fresh token right before opening the importer.
    const response = await fetch("/your-api/import/session", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${accessToken}`,
      },
    });

    // Return the short-lived token. Do not reuse or cache it between
    // imports.
    const { token } = await response.json();
    return token;
  },
  importNamespace: "user-import",
});

Choose the right environment key

Use the secret key for the environment where the importer will run.

• Production

  • Use for: live imports in your production deployment
  • Plan requirement: paid plan required
  • Usage: counts toward usage limits
  • Import behavior: full live imports

• Development

  • Use for: local development, staging, and CI deployments
  • Plan requirement: available on all teams
  • Usage: unlimited test imports
  • Import behavior: returns only the first 100 rows and shows a test mode banner

How to implement the session endpoint

Your backend session endpoint should:

• Call the Create Import Auth Token REST API with your environment secret key
• Return only the resulting token to the browser

The example below uses Hono, but the same pattern applies in any backend framework.

import { Hono } from "hono";

const app = new Hono();

app.post("/your-api/import/session", async (c) => {
  // Keep your ExpressCSV secret key on the backend.
  const response = await fetch("https://api.expresscsv.com/v1/importer/auth-tokens", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.YOUR_EXPRESSCSV_SECRET_KEY}`,
    },
  });

  if (!response.ok) {
    return c.json({ error: "Failed to create auth token" }, 500);
  }

  // Send only the short-lived token back to the browser.
  const { token } = await response.json();
  return c.json({ token });
});

export default app;