Express CSV Logo

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",
});

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:

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;

On this page

Choose the right environment keyHow to implement the session endpoint