Session tokens

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

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

const importer = new CSVImporter({
  schema,
  getSessionToken: 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",
});

Never expose the secret to the browser

Client code should only receive short-lived session tokens from your backend. If the secret is exposed, rotate it in the ExpressCSV dashboard and update your backend.

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 Session 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/sessions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.YOUR_EXPRESSCSV_SECRET_KEY}`,
    },
  });

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

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

export default app;

Choose the right environment key

How to implement the session endpoint

On this page