Skip to main content

Migrating from your current system

Bulk-import your existing organizations, users, roles, and applications with a validate-then-commit flow, so you never half-apply a bad file.

The flow​

  1. Validate (dry run) — POST /api/import/validate with your payload. Nothing is written. You get back a report: what would be created, plus any errors (bad references, duplicate identifiers, an import that would exceed your plan's application-set cap).
  2. Commit — if the report has no errors, POST /api/import/commit with the same payload applies it.
  3. Track — GET /api/import/jobs lists past import jobs and their status.
const report = await mgmt.import.validate(payload);
if (report.errors.length === 0) {
  await mgmt.import.commit(payload);
}

Payload shape​

The payload carries organizations, users, roles, and applications, each keyed by a stable externalId you assign. References between entities (a user's org, a role's permissions) use those external ids, so the graph resolves in one pass regardless of order. External ids are also how a re-run stays idempotent — an entity already imported is skipped, not duplicated.

Tips​

  • Run validate as many times as you like; it's side-effect-free.
  • Fix every reported error before committing — a commit applies the whole file.
  • Importing is capped by your plan just like manual registration; the dry run tells you before you commit.

Each SDK's README has a language-specific migration walkthrough with a full example payload.