Multi-company

Today: one API key per company

A Simplo API key is bound to exactly one company — the credential is the company. To operate several companies, keep one key per company and create one client per company:

import Simplo from '@simplohq/sdk';

const clients = new Map(
  [
    ['acme', process.env.SIMPLO_API_KEY_ACME!],
    ['globex', process.env.SIMPLO_API_KEY_GLOBEX!],
  ].map(([name, apiKey]) => [name, new Simplo({ apiKey })]),
);

const dte = await clients.get('acme')!.dtes.emit({ /* ... */ });

This model is simple and safe: a leaked key exposes exactly one company, keys are revocable per company, and there’s no way to target the wrong tenant by passing the wrong ID.

Each company can hold sandbox (sk_simplo_sandbox_...) and live (sk_simplo_...) keys at the same time — the key also fixes the environment, not just the company. With your session, GET /api/v1/portfolio/apikeys lists the keys across all your companies (with their is_sandbox flag).

Don’t multiplex by mutating a shared client: one client per company, each with its own key.

On the roadmap: platform accounts with companyId

For platforms that manage many companies under a single credential, the SDK already ships a company selector — the companyId client option and its per-request override — sent as the X-Company-Id header:

const simplo = new Simplo({ apiKey, companyId: 'co_default' });

await simplo.dtes.emit(params, { companyId: 'co_other' });

Current state: the option is reserved. Platform credentials that accept X-Company-Id are on the roadmap and not yet available; today the API ignores the header entirely — the key still fixes the company, so don’t rely on companyId to select a tenant. If you’re building a platform on top of Simplo and need this, write to [email protected].

Related

• Authentication — how keys work
• For coding agents — multi-company rules for agents