Platform

For the platform operator only, with a platform key or a session of the operator portal: provision organizations, list and open them, suspend and reactivate them, invite their administrators, mark a demo, export an organization's data for its offboarding, read the audit record. A tenant's keys and sessions do not work here, and a platform credential works nowhere else.

GET /v1/platform/audit

List the operator's audit record

What the operator did and who tried, newest first: sign-ins (and refused ones), sign-outs, provisioning, suspension, reactivation, marking a demo (and refusals), inviting an administrator, opening an organization, and purging a demo. Each row names who (an operator's address or a platform key), from which client address, which organization and the outcome. The record is append-only. 404 for an unknown before. Needs the platform:read scope.

Parameters

Example request

curl "$ERP_URL/v1/platform/audit" \
  -H "Authorization: Bearer $PLATFORM_KEY"

Responses

Example response (shape)

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "at": "2026-09-21T09:30:00Z",
    "action": "string",
    "outcome": "denied",
    "actor": {},
    "address": "string",
    "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "org_name": "string",
    "detail": {}
  }
]

POST /v1/platform/auth/google

Sign in to the operator portal with Google

Exchange a Google ID token for an operator session cookie. For the operator portal (/admin), not for scripts: a script uses a platform key.

The token is verified as the web UI's is (signature, audience, expiry, verified email), and the account must also belong to its own Google Workspace (the hd claim is the address's domain), be of an allowed domain when the deployment limits them, and be on the list of platform operators (ERP_PLATFORM_OPERATORS). On success the cookie erp_platform_session is set (HttpOnly, SameSite=Strict, path /v1/platform; Secure on https and in the cloud): it lasts 8 hours and ends after 30 idle minutes, and it authenticates /v1/platform and nothing else. Every attempt, successful or refused, is recorded in the platform audit. Needs the X-ERP-UI: 1 header (403 csrf without it). Refused with 403 for a token that does not verify or an account that is not an operator; 422 when Google sign-in is not configured.

Request body

application/json (required): OperatorGoogleLogin

Example request

curl -X POST "$ERP_URL/v1/platform/auth/google" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "credential": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ij..."
}'

Responses

Example response (shape)

{
  "status": "signed_in",
  "email": "string",
  "expires_at": "2026-09-21T09:30:00Z"
}

POST /v1/platform/auth/logout

Sign out of the operator portal

End the operator session whose cookie accompanies the request (it is revoked, not only forgotten) and clear the cookie; recorded in the platform audit. With a platform key there is no session and nothing happens. The response has no body. Needs platform:read and, for a session, the X-ERP-UI: 1 header.

Example request

curl -X POST "$ERP_URL/v1/platform/auth/logout" \
  -H "Authorization: Bearer $PLATFORM_KEY"

Responses

GET /v1/platform/charts

List chart templates

The chart-of-accounts templates a new entity can start from, the value of chart in POST /v1/platform/organizations. With country, the country's standard chart is marked standard: the one an entity of that country gets when the request names no chart (the Swiss KMU chart for CH and LI, the German HGB chart for DE, the French, Italian and Spanish national charts for FR, IT and ES, the generic IFRS chart for a country without one of its own). Needs the platform:read scope.

Parameters

Example request

curl "$ERP_URL/v1/platform/charts" \
  -H "Authorization: Bearer $PLATFORM_KEY"

Responses

Example response (shape)

[
  {
    "id": "string",
    "name": "string",
    "countries": [
      "string"
    ],
    "standard": false
  }
]

GET /v1/platform/health

Service health: SLOs, error budget, latency, uptime and deploy

How the two services are doing against their objectives, for the operator's console. Per service (erp-api, datavnext-api): each service level objective with its internal target, its compliance over the rolling 28 days and the share of its error budget still unspent (availability: requests that are not a 5xx, among the requests of real callers; latency: the share of reads or writes the application answered under a threshold; the objectives and thresholds are defined in Terraform and named in each entry), the 95th percentile of the last 24 hours by request class (read, report, write, heavy), and the version, revision and time of the last deploy. Also the synthetic uptime checks (probes from outside, every five minutes).

The figures come from Cloud Monitoring and Cloud Run, read with the service's own identity, and are cached for 60 seconds. A part that cannot be read is named in problems and the rest is still answered (status is then degraded; unavailable when nothing could be read, which is also the answer where monitoring is not configured). Counts and durations of requests only: no organization, person or amount. Needs the platform:read scope.

Example request

curl "$ERP_URL/v1/platform/health" \
  -H "Authorization: Bearer $PLATFORM_KEY"

Responses

Example response (shape)

{
  "generated_at": "2026-09-21T09:30:00Z",
  "status": "degraded",
  "services": [
    {
      "id": "string",
      "name": "string",
      "slos": [
        null
      ],
      "latency_p95_ms_24h": {},
      "deploy": null
    }
  ],
  "uptime_checks": [
    {
      "name": "string",
      "url": "string",
      "status": "down",
      "success_ratio_15m": 1.5,
      "success_ratio_24h": 1.5
    }
  ],
  "problems": [
    {
      "section": "string",
      "reason": "string"
    }
  ]
}

GET /v1/platform/me

Who the platform credential is

The operator behind the request: operator:<address> for a session of the operator portal (with the address as email), platform:<prefix> for a platform key. The portal asks it to learn whether the session is still valid; it ends after session_hours from sign-in and after idle_minutes without a request. workspace_domains are the deployment's own Google Workspace domains, whose people sign in with Google: the portal warns when a customer's administrator is invited on one. Needs the platform:read scope.

Example request

curl "$ERP_URL/v1/platform/me" \
  -H "Authorization: Bearer $PLATFORM_KEY"

Responses

Example response (shape)

{
  "id": "string",
  "name": "string",
  "email": "string",
  "via": "key",
  "scopes": [
    "string"
  ],
  "session_hours": 1,
  "idle_minutes": 1,
  "workspace_domains": [
    "string"
  ]
}

GET /v1/platform/models

Show the models behind the built-in agents

The models the built-in agents (bill capture, reconciliation, close review, Q&A) ask, in order: the first answers unless it fails or does not answer within two minutes, then the next (a refusal is an answer: no other model is asked). source says whether they are the operator's latest choice or the deployment's defaults. available lists the Gemini models Vertex AI offers at the region now, so that a newer one can be chosen without a deploy (the list is cached for ten minutes; Claude models are not listed by Google). history is the latest choices. Needs the platform:read scope.

Example request

curl "$ERP_URL/v1/platform/models" \
  -H "Authorization: Bearer $PLATFORM_KEY"

Responses

Example response (shape)

{
  "models": [
    "string"
  ],
  "source": "deployment",
  "last_resort": [
    "string"
  ],
  "not_listed": [
    "string"
  ],
  "deployment_default": [
    "string"
  ],
  "region": "string",
  "configured": true,
  "available": [
    "string"
  ],
  "available_error": "string",
  "history": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "models": [
        "string"
      ],
      "created_at": "2026-09-21T09:30:00Z",
      "created_by": {},
      "reason": "string"
    }
  ]
}

PUT /v1/platform/models

Choose the models behind the built-in agents

Choose the models the built-in agents ask, in order (1 to 4 Vertex AI model ids of the Gemini or Claude family, each once). They are used from the next agent run on, for every organization, and replace the deployment's defaults; a Claude model must be enabled in Model Garden first. Check a model with POST /v1/platform/models/check before choosing it. A choice is never changed or deleted: a new one replaces it, and each is recorded in the platform audit (platform.choose_models, with the previous models). Only an operator signed in to the portal may: a platform key is refused with 403 (and recorded). 422 for an id that is not a Gemini or Claude model id, or one named twice. Needs the platform:provision scope.

Request body

application/json (required): ModelChoiceInput

Example request

curl -X PUT "$ERP_URL/v1/platform/models" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "models": [
    "gemini-3.8-flash",
    "gemini-3.7-flash"
  ],
  "reason": "3.7 as the fallback while 3.8 is in preview"
}'

Responses

Example response (shape)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "models": [
    "string"
  ],
  "created_at": "2026-09-21T09:30:00Z",
  "created_by": {},
  "reason": "string"
}

POST /v1/platform/models/check

Check that a model answers

Ask one model, without fallback, a short test question at the configured Vertex AI region, and say whether it answered and how long it took. No organization's data is sent. The check is recorded in the platform audit (platform.check_model, outcome ok or failed). A model that is unknown, not enabled or not served at the region answers ok: false with the provider's error. 503 when no Google Cloud project is configured. Needs the platform:provision scope.

Request body

application/json (required): ModelCheckInput

Example request

curl -X POST "$ERP_URL/v1/platform/models/check" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gemini-3.8-flash"
}'

Responses

Example response (shape)

{
  "model": "string",
  "ok": true,
  "seconds": 1.5,
  "error": "string"
}

GET /v1/platform/organizations

List organizations

The organizations on the platform, oldest first, with their lifecycle state (active or suspended), their kind (customer or demo), when and by whom each was created and why it was last suspended or reactivated. With usage=true each also has the number of entities, people, journal entries and documents and when it was last used (that read is recorded in the platform audit as org.list_usage). Never any accounting data beyond counts. Pages of limit: pass the last org_id as after for the next one. Needs the platform:read scope.

Parameters

Example request

curl "$ERP_URL/v1/platform/organizations" \
  -H "Authorization: Bearer $PLATFORM_KEY"

Responses

Example response (shape)

[
  {
    "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "status": "active",
    "created_at": "2026-09-21T09:30:00Z",
    "created_by": {},
    "status_changed_at": "2026-09-21T09:30:00Z",
    "status_reason": "string",
    "kind": "customer",
    "copy_of": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "remove_requested_at": "2026-09-21T09:30:00Z",
    "delete_after": "2026-09-21T09:30:00Z",
    "usage": {
      "entities": 1,
      "users": 1,
      "entries": 1,
      "documents": 1,
      "last_activity_at": null,
      "last_sign_in_at": null
    }
  }
]

POST /v1/platform/organizations

Provision an organization

Create an organization with its entities and invite its first people, in one step.

Each entity starts from a template (ch_sme, de_sme or generic: country, functional currency, chart of accounts, VAT method, fiscal calendar), which the request can override. The chart brings every account of the roles the services need. The first administrator (admin) and any users are invited by email. When password sign-in is configured, Google e-mails each of them the link that sets their password (password_email_sent), except to an address of the deployment's Google Workspace domains, whose people sign in with Google. The e-mails go out last, once everything is written; if Google refuses (502), nothing is created and the request can be repeated. No key is created; the administrator creates their own API key after the first sign-in, and it is bound to them.

All or nothing: if anything fails (an unknown chart, an entity code twice, an address invited twice) nothing is created. A retry with the same Idempotency-Key and body returns the stored response; the same key with another body answers 409. Needs the platform:provision scope. The creation is an audit event of the new organization (org.create, entity.create, user.invite, by platform:<prefix> or, from the operator portal, operator:<address>), a security event (platform.organization.provision) and a row of the platform audit. replayed is true when the answer is the stored one of an earlier request with the same key. Refused: 401 without a valid platform key or operator session, 403 without the scope, 409 for a reused key or an entity code or address twice, 422 for an unknown chart or a template without country or currency.

Request body

application/json (required): ProvisionInput

Example request

curl -X POST "$ERP_URL/v1/platform/organizations" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "admin": {
    "email": "petra.muster@example.com",
    "name": "Petra Muster"
  },
  "entities": [
    {
      "code": "CH01",
      "fiscal_years": [
        2026
      ],
      "name": "Muster Treuhand AG",
      "template": "ch_sme",
      "vat_number": "CHE-123.456.788 MWST"
    }
  ],
  "name": "Muster Treuhand AG",
  "users": [
    {
      "email": "hans.keller@example.com",
      "name": "Hans Keller"
    }
  ]
}'

Responses

Example response (shape)

{
  "organization": {
    "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "status": "active",
    "created_at": "2026-09-21T09:30:00Z",
    "created_by": {},
    "status_changed_at": "2026-09-21T09:30:00Z",
    "status_reason": "string",
    "kind": "customer",
    "copy_of": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "remove_requested_at": "2026-09-21T09:30:00Z",
    "delete_after": "2026-09-21T09:30:00Z"
  },
  "entities": [
    {
      "code": "string",
      "name": "string",
      "country": "string",
      "functional_currency": "string",
      "chart": "string",
      "role_accounts": 1,
      "fiscal_years": [
        1
      ],
      "vat_method": "string"
    }
  ],
  "users": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "email": "string",
      "scopes": [
        "string"
      ],
      "status": "string",
      "password_email_sent": false
    }
  ],
  "replayed": false
}

GET /v1/platform/organizations/{org_id}

Get an organization

One organization as the operator sees it: its lifecycle state and kind, its entities (code, name, country, currency), its people (address, role, status, last sign-in), its counts and the evidence of use that decides whether it may be marked as a demo. Master data and counts only: no ledger line, amount or document. Opening an organization is recorded in the platform audit (org.view). 404 for an unknown id. Needs the platform:read scope.

Parameters

Example request

curl "$ERP_URL/v1/platform/organizations/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $PLATFORM_KEY"

Responses

Example response (shape)

{
  "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "status": "active",
  "created_at": "2026-09-21T09:30:00Z",
  "created_by": {},
  "status_changed_at": "2026-09-21T09:30:00Z",
  "status_reason": "string",
  "kind": "customer",
  "copy_of": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "remove_requested_at": "2026-09-21T09:30:00Z",
  "delete_after": "2026-09-21T09:30:00Z",
  "usage": {
    "entities": 1,
    "users": 1,
    "entries": 1,
    "documents": 1,
    "last_activity_at": "2026-09-21T09:30:00Z",
    "last_sign_in_at": "2026-09-21T09:30:00Z"
  },
  "entities": [
    {
      "code": "string",
      "name": "string",
      "country": "string",
      "functional_currency": "string"
    }
  ],
  "users": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "email": "string",
      "name": "string",
      "role": "string",
      "status": "string",
      "created_at": "2026-09-21T09:30:00Z",
      "last_login_at": "2026-09-21T09:30:00Z"
    }
  ],
  "evidence": {
    "users": 1,
    "users_not_administrators": 1,
    "users_invited_by_people": 1,
    "users_signed_in": 1,
    "journal_entries": 1,
    "journal_entries_not_by_the_seed": 1,
    "documents": 1,
    "documents_not_by_the_seed": 1,
    "document_dispatches": 1,
    "issued_outputs_archived": 1,
    "bank_statements": 1,
    "first_posting": "2026-09-21",
    "last_posting": "2026-09-21",
    "customer_grade": [
      "string"
    ]
  }
}

POST /v1/platform/organizations/{org_id}/admins

Invite or show again an organization's first administrator

Invite an administrator of an existing organization, who signs in with the Google account of the address or, without one, with a password. A person who is not a user yet is added (invited); one who was invited and has not signed in is left as they are (already_invited) and the answer says again where to sign in. When password sign-in is configured, Google e-mails them the link that sets their password, a fresh one each time (password_email_sent; not to an address of the deployment's Google Workspace domains; 502 when Google refuses). Both are recorded in the platform audit; a new invitation is also an event of the organization's audit trail. Safe to repeat. 409 for a person who has signed in, who is disabled or who was invited with another role; 404 for an unknown organization. Needs the platform:provision scope.

Parameters

Request body

application/json (required): AdminInvite

Example request

curl -X POST "$ERP_URL/v1/platform/organizations/3fa85f64-5717-4562-b3fc-2c963f66afa6/admins" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "petra.muster@example.com",
  "name": "Petra Muster"
}'

Responses

Example response (shape)

{
  "user": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "string",
    "scopes": [
      "string"
    ],
    "status": "string",
    "password_email_sent": false
  },
  "result": "already_invited",
  "sign_in_path": "string",
  "password_email_sent": false
}

POST /v1/platform/organizations/{org_id}/delete

Delete an organization

Delete an organization and its test copies, with everything they hold (ADR-0042). Only an operator signed in to the portal may: a platform key is refused with 403. confirm_name must be the organization's exact name (422 otherwise). An organization that shows signs of real use (the evidence of its detail) is refused with 409 customer_activity unless accept_activity is true. The answer is 202: from now on nobody reaches the organization. For an hour (until delete_after) the deletion can be undone (undo-delete); after that the owner's job, which runs every hour and at every deploy, deletes it with the demo purge over the owner connection (ADR-0022) and records how many rows it deleted, and nothing brings its books back but a restore of the database. Asking again changes nothing. The request and a refusal are recorded in the platform audit. 404 for an unknown id. Needs the platform:provision scope.

Parameters

Request body

application/json (required): DeleteOrganizationInput

Example request

curl -X POST "$ERP_URL/v1/platform/organizations/3fa85f64-5717-4562-b3fc-2c963f66afa6/delete" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "confirm_name": "Muster Treuhand AG"
}'

Responses

Example response (shape)

{
  "organization": {
    "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "status": "active",
    "created_at": "2026-09-21T09:30:00Z",
    "created_by": {},
    "status_changed_at": "2026-09-21T09:30:00Z",
    "status_reason": "string",
    "kind": "customer",
    "copy_of": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "remove_requested_at": "2026-09-21T09:30:00Z",
    "delete_after": "2026-09-21T09:30:00Z"
  },
  "changed": true,
  "evidence": {
    "users": 1,
    "users_not_administrators": 1,
    "users_invited_by_people": 1,
    "users_signed_in": 1,
    "journal_entries": 1,
    "journal_entries_not_by_the_seed": 1,
    "documents": 1,
    "documents_not_by_the_seed": 1,
    "document_dispatches": 1,
    "issued_outputs_archived": 1,
    "bank_statements": 1,
    "first_posting": "2026-09-21",
    "last_posting": "2026-09-21",
    "customer_grade": [
      "string"
    ]
  }
}

GET /v1/platform/organizations/{org_id}/exports

List an organization's exports

The organization's exports, newest first, with their status, whoever asked for them. Pages of limit: pass the last id as after for the next one. Needs the platform:read scope. 404 for an unknown organization.

Parameters

Example request

curl "$ERP_URL/v1/platform/organizations/3fa85f64-5717-4562-b3fc-2c963f66afa6/exports" \
  -H "Authorization: Bearer $PLATFORM_KEY"

Responses

Example response (shape)

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "expired",
    "via": "platform",
    "language": "de",
    "note": "string",
    "requested_by": {},
    "requested_at": "2026-09-21T09:30:00Z",
    "started_at": "2026-09-21T09:30:00Z",
    "finished_at": "2026-09-21T09:30:00Z",
    "stage": "string",
    "progress": {},
    "error": "string",
    "cutoff": "2026-09-21T09:30:00Z",
    "file_name": "string",
    "size_bytes": 1,
    "sha256": "string",
    "manifest_sha256": "string",
    "file_count": 1,
    "row_count": 1,
    "complete": true,
    "statement": {},
    "expires_at": "2026-09-21T09:30:00Z"
  }
]

POST /v1/platform/organizations/{org_id}/exports

Export an organization's data

Ask for the complete package of an organization's data, as the organization's own administrators can (POST /v1/exports): every table as CSV and JSON, the reports as PDF and CSV, every stored file checked against its SHA-256, the hash-chain verification, a manifest with the hash of every file, the README, and for a German entity the index.xml. Meant for offboarding: suspend the organization first (POST .../suspend), then export, then hand over. The export runs asynchronously from one consistent snapshot; follow it with GET .../exports/{id}.

The platform reads none of the books through this API: the job that builds the package does, over the database's row-level security, scoped to the one organization. When it has succeeded, the SHA-256 of the package is recorded in the platform's append-only audit record (platform_audit, action org.export), so that we can later attest what was handed over. One export at a time per organization (409 export_in_progress). Needs the platform:provision scope. Starting is an audit event of the organization (export.start, by platform:<prefix>), a security event (platform.export.start) and a row of the operator's record (org.export_start). 404 for an unknown organization. A retry with the same Idempotency-Key returns the first answer.

Parameters

Request body

application/json (required): ExportRequest

Example request

curl -X POST "$ERP_URL/v1/platform/organizations/3fa85f64-5717-4562-b3fc-2c963f66afa6/exports" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "language": "de",
  "note": "Archive copy at contract end"
}'

Responses

Example response (shape)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "expired",
  "via": "platform",
  "language": "de",
  "note": "string",
  "requested_by": {},
  "requested_at": "2026-09-21T09:30:00Z",
  "started_at": "2026-09-21T09:30:00Z",
  "finished_at": "2026-09-21T09:30:00Z",
  "stage": "string",
  "progress": {},
  "error": "string",
  "cutoff": "2026-09-21T09:30:00Z",
  "file_name": "string",
  "size_bytes": 1,
  "sha256": "string",
  "manifest_sha256": "string",
  "file_count": 1,
  "row_count": 1,
  "complete": true,
  "statement": {},
  "expires_at": "2026-09-21T09:30:00Z"
}

GET /v1/platform/organizations/{org_id}/exports/{run_id}

Get an organization's export

One export with its status and, once it has succeeded, the file's SHA-256 and the hand-over statement. 404 for an unknown organization or an export of another one. Needs the platform:read scope.

Parameters

Example request

curl "$ERP_URL/v1/platform/organizations/3fa85f64-5717-4562-b3fc-2c963f66afa6/exports/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $PLATFORM_KEY"

Responses

Example response (shape)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "expired",
  "via": "platform",
  "language": "de",
  "note": "string",
  "requested_by": {},
  "requested_at": "2026-09-21T09:30:00Z",
  "started_at": "2026-09-21T09:30:00Z",
  "finished_at": "2026-09-21T09:30:00Z",
  "stage": "string",
  "progress": {},
  "error": "string",
  "cutoff": "2026-09-21T09:30:00Z",
  "file_name": "string",
  "size_bytes": 1,
  "sha256": "string",
  "manifest_sha256": "string",
  "file_count": 1,
  "row_count": 1,
  "complete": true,
  "statement": {},
  "expires_at": "2026-09-21T09:30:00Z"
}

GET /v1/platform/organizations/{org_id}/exports/{run_id}/download

Download an organization's export

The package of a succeeded export, as a ZIP, streamed through the API (use a client that writes to a file; for a large package prefer the link). Every download is an audit event of the organization (export.download), a security event (platform.export.download) and a row of the operator's record (org.export_download). Needs the platform:provision scope. 409 export_not_ready unless the export succeeded and has not expired.

Parameters

Example request

curl "$ERP_URL/v1/platform/organizations/3fa85f64-5717-4562-b3fc-2c963f66afa6/exports/3fa85f64-5717-4562-b3fc-2c963f66afa6/download" \
  -H "Authorization: Bearer $PLATFORM_KEY"

Responses

GET /v1/platform/organizations/{org_id}/exports/{run_id}/link

Get a link to download an organization's export

A signed link that downloads the package straight from the store without credentials, for seven days at most and never beyond the package's expiry: this is how the package is handed over to the customer, who has no platform key. Anyone who holds the link can download until it ends: send it over a channel you trust, together with the statement (GET .../exports/{id}: SHA-256 of the file). Giving the link is an audit event (export.link), a security event (platform.export.download) and a row of the operator's record (org.export_link). Needs the platform:provision scope. 409 export_not_ready unless the export succeeded and has not expired, 409 no_signed_link where links cannot be signed (use /download).

Parameters

Example request

curl "$ERP_URL/v1/platform/organizations/3fa85f64-5717-4562-b3fc-2c963f66afa6/exports/3fa85f64-5717-4562-b3fc-2c963f66afa6/link" \
  -H "Authorization: Bearer $PLATFORM_KEY"

Responses

Example response (shape)

{
  "url": "string",
  "expires_at": "2026-09-21T09:30:00Z",
  "file_name": "string",
  "size_bytes": 1,
  "sha256": "string"
}

POST /v1/platform/organizations/{org_id}/mark-demo

Mark an organization as a demo

Make an organization a demo: the one kind the operator may purge (with a command, never through this API; a customer's books are never deleted). Only an operator signed in to the portal may: a platform key is refused with 403. confirm_name must be the organization's exact name (422 otherwise). It is done by a database function that also checks the evidence of use: an organization that shows any sign of real use (an invoice sent to a customer, a file archived as issued, a person who is not an administrator or was invited by a person or a key, more than one person who has signed in, entries or documents not created by the demo seed) is refused with 409 customer_activity, and the evidence is in the answer. There is no way to accept it here: an organization that was used is marked only by the command erp platform mark-demo --accept-activity on the owner connection. A marking and a refusal are recorded in the platform audit. Marking a demo again changes and records nothing. 404 for an unknown id. Needs the platform:provision scope.

Parameters

Request body

application/json (required): MarkDemoInput

Example request

curl -X POST "$ERP_URL/v1/platform/organizations/3fa85f64-5717-4562-b3fc-2c963f66afa6/mark-demo" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "confirm_name": "Muster Treuhand AG"
}'

Responses

Example response (shape)

{
  "organization": {
    "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "status": "active",
    "created_at": "2026-09-21T09:30:00Z",
    "created_by": {},
    "status_changed_at": "2026-09-21T09:30:00Z",
    "status_reason": "string",
    "kind": "customer",
    "copy_of": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "remove_requested_at": "2026-09-21T09:30:00Z",
    "delete_after": "2026-09-21T09:30:00Z"
  },
  "changed": true,
  "evidence": {
    "users": 1,
    "users_not_administrators": 1,
    "users_invited_by_people": 1,
    "users_signed_in": 1,
    "journal_entries": 1,
    "journal_entries_not_by_the_seed": 1,
    "documents": 1,
    "documents_not_by_the_seed": 1,
    "document_dispatches": 1,
    "issued_outputs_archived": 1,
    "bank_statements": 1,
    "first_posting": "2026-09-21",
    "last_posting": "2026-09-21",
    "customer_grade": [
      "string"
    ]
  }
}

POST /v1/platform/organizations/{org_id}/passkey-reset

Reset a person's passkeys

For a person of the organization who lost every device with a passkey and has no administrator to ask, such as a company's only owner: remove their passkeys and end all their sessions, in every organization; their next sign-in creates a new first passkey. Only an operator signed in to the portal (403 for a platform key), with the platform:provision scope. 404 when the address is not a user of the organization. Recorded in the platform audit (org.passkey_reset), the organization's audit trail (user.passkey_reset) and as a security event (passkey.reset).

Parameters

Request body

application/json (required): OperatorPasskeyReset

Example request

curl -X POST "$ERP_URL/v1/platform/organizations/3fa85f64-5717-4562-b3fc-2c963f66afa6/passkey-reset" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "erin@example.com"
}'

Responses

Example response (shape)

{
  "email": "string",
  "removed": 1
}

POST /v1/platform/organizations/{org_id}/reactivate

Reactivate an organization

Lift a suspension: the organization can change data again. The reason goes to the audit trail (org.reactivate) and to a security event. Safe to repeat: an organization that is already active is returned unchanged. 404 for an unknown id. Needs the platform:provision scope.

Parameters

Request body

application/json (required): StatusChange

Example request

curl -X POST "$ERP_URL/v1/platform/organizations/3fa85f64-5717-4562-b3fc-2c963f66afa6/reactivate" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Invoice 2026-114 unpaid after two reminders"
}'

Responses

Example response (shape)

{
  "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "status": "active",
  "created_at": "2026-09-21T09:30:00Z",
  "created_by": {},
  "status_changed_at": "2026-09-21T09:30:00Z",
  "status_reason": "string",
  "kind": "customer",
  "copy_of": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "remove_requested_at": "2026-09-21T09:30:00Z",
  "delete_after": "2026-09-21T09:30:00Z"
}

POST /v1/platform/organizations/{org_id}/suspend

Suspend an organization

Make an organization read-only. From now on its API keys and sessions can read everything and change nothing: every request that would change state answers 403 (suspended); signing in and out still work. Nothing is deleted. The reason goes to the organization's audit trail (org.suspend) and to a security event. Safe to repeat: an organization that is already suspended is returned unchanged. 404 for an unknown id. Needs the platform:provision scope.

Parameters

Request body

application/json (required): StatusChange

Example request

curl -X POST "$ERP_URL/v1/platform/organizations/3fa85f64-5717-4562-b3fc-2c963f66afa6/suspend" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Invoice 2026-114 unpaid after two reminders"
}'

Responses

Example response (shape)

{
  "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "status": "active",
  "created_at": "2026-09-21T09:30:00Z",
  "created_by": {},
  "status_changed_at": "2026-09-21T09:30:00Z",
  "status_reason": "string",
  "kind": "customer",
  "copy_of": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "remove_requested_at": "2026-09-21T09:30:00Z",
  "delete_after": "2026-09-21T09:30:00Z"
}

POST /v1/platform/organizations/{org_id}/undo-delete

Undo the deletion of an organization

Undo a deletion asked for less than an hour ago (before delete_after): the organization, and the test copies deleted with it, are reachable again as they were. Only an operator signed in to the portal may: a platform key is refused with 403. After the hour the owner's job may be deleting it: 409. Safe to repeat: an organization whose deletion was not asked for is returned unchanged. Recorded in the platform audit (org.delete_undone). 404 for an unknown id. Needs the platform:provision scope.

Parameters

Example request

curl -X POST "$ERP_URL/v1/platform/organizations/3fa85f64-5717-4562-b3fc-2c963f66afa6/undo-delete" \
  -H "Authorization: Bearer $PLATFORM_KEY"

Responses

Example response (shape)

{
  "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "status": "active",
  "created_at": "2026-09-21T09:30:00Z",
  "created_by": {},
  "status_changed_at": "2026-09-21T09:30:00Z",
  "status_reason": "string",
  "kind": "customer",
  "copy_of": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "remove_requested_at": "2026-09-21T09:30:00Z",
  "delete_after": "2026-09-21T09:30:00Z"
}

Schemas

AdminInvite

AdminInvited

DeleteOrganizationInput

DeleteOrganizationResult

DeployOut

What the Cloud Run service runs.

EntitySummary

MarkDemoInput

MarkDemoResult

ModelCheck

ModelCheckInput

ModelChoiceInput

ModelChoiceOut

ModelSettings

OperatorGoogleLogin

OperatorMe

OperatorPasskeyReset

OperatorPasskeyResetDone

OperatorSignedIn

OrganizationDetail

One organization as the operator sees it: master data and counts, never the books.

OrganizationEvidence

The signs of real use that decide whether an organization may be marked as a demo (org_activity, ADR-0022). A non-empty customer_grade means it looks like a customer.

OrganizationSummary

A row of the operator's list: the lifecycle, and the usage when it was asked for.

OrganizationUsage

What an organization has been used for: counts only, never a ledger line or an amount.

OrganizationUser

PlatformAuditOut

Problem

ProvisionAdmin

ProvisionEntity

ProvisionInput

ProvisionUser

Provisioned

ProvisionedEntity

ProvisionedUser

ServiceHealth

ServiceOut

SloOut

One service level objective of a service, over its rolling window.

StatusChange

TenantOut

An organization as the platform sees it: its lifecycle, never its books.

UptimeCheckOut

A synthetic probe from outside Google's network, every five minutes.