Provisioning (Fleet)

The provisioning endpoint lets an app stand up a new project in its own tenant — for example, onboarding a new merchant in a storefront fleet — entirely through the public API, with no first-party platform access.

It is a fleet capability: the new project joins a fleet group and inherits that group’s shared, centrally-managed schema, so every project in the fleet runs one identical schema while its data stays isolated per project. Provisioning is available to fleet-enabled tenants.

Authentication

Provisioning requires a secret tenant key (sk_t_) that holds the provision scope. The endpoint rejects publishable keys, project-bound keys, and control keys, and it refuses browser requests (no Origin / Sec-Fetch-Site).

The new project is always created in the key’s own tenant — the tenant is taken from the credential, never from the request body — so a key can only ever provision within its own tenant.

Provision a project


POST https://api.foir.dev/v1/provision

Field	Required	Description
`provision_id`	yes	A caller-chosen idempotency key (e.g. your external merchant id). Re-sending the same `provision_id` returns the existing result instead of creating a second project.
`group_id`	yes	The fleet group the new project joins. It is pinned to the group’s current published schema.
`name`	yes	Display name for the new project.
`branding`	no	Optional branding/theme to apply to the new project.
`allow_list_key_ids`	no	IDs of tenant data keys whose project allow-list should be extended to include the new project, so an existing storefront key can read it immediately.

Because the call is authenticated with a tenant key, include an X-Project-Id header naming any project already on the key’s allow-list. It satisfies tenant-key authentication; the new project’s identity comes from the provisioning operation, not this header.


curl -X POST https://api.foir.dev/v1/provision \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_t_..." \
  -H "X-Project-Id: <any-allow-listed-project-id>" \
  -d '{
    "provision_id": "merchant-12345",
    "group_id": "<fleet-group-id>",
    "name": "New Merchant"
  }'

A successful response reports the outcome and the new project’s id:


{
  "provision_id": "merchant-12345",
  "project_id": "<new-project-id>",
  "status": "completed",
  "schema_version": "<pinned-schema-version>",
  "steps": {
    "created_project": true,
    "group_joined": true,
    "branding_set": true,
    "allow_list_extended": true
  }
}

The operation is a saga — composed, idempotent, and resumable. If a step fails partway, re-sending the same provision_id resumes from where it left off rather than duplicating work; a completed provision_id short-circuits and returns the existing result.

Check provisioning status


GET https://api.foir.dev/v1/provision/{provision_id}

Returns the same status payload for an in-flight or completed provision. Authenticate with the same sk_t_ + provision key (and the X-Project-Id header).


curl https://api.foir.dev/v1/provision/merchant-12345 \
  -H "x-api-key: sk_t_..." \
  -H "X-Project-Id: <any-allow-listed-project-id>"

Notes

Data isolation is unchanged. A provisioned project shares only the fleet group’s schema; its records and customers are isolated per project like any other Foir project.
No keys are minted for you. Provisioning does not create per-project pk_/sk_ keys. Serve the new project through your existing tenant key — pass its id with X-Project-Id (use allow_list_key_ids so the key can reach it immediately).