Partner Installations

Partner installations create application-managed projects inside the BotDojo account assigned to a partner credential. The partner credential is used only to provision installations.

Provision an installation

POST /api/v1/partners/installations

Required headers:

Content-Type: application/json
X-Partner-Key-Id: ptk_...
X-Partner-Timestamp: <current Unix timestamp in seconds>
X-Partner-Nonce: <24-128 character random base64url value>
X-Partner-Signature: <lowercase hex HMAC-SHA256>
X-Partner-Version: 1

Create the signature from the method, exact request path, timestamp, nonce, and lowercase hexadecimal SHA-256 hash of the exact request bytes. Join those five values with \n and compute HMAC-SHA256 with the partner secret.

Example body:

{
	"external_installation_id": "merchant-123",
	"display_name": "Example Merchant",
	"admin_origins": ["https://admin.partner.example"],
	"storefront_origins": ["https://shop.example"],
	"metadata": {}
}

The first successful request returns HTTP 201:

{
	"installation_id": "<uuid>",
	"project_api_key": "<shown-once-key>",
	"created": true,
	"application": {}
}

Store the project key immediately. An idempotent retry returns HTTP 200 with the same installation ID and created: false, but does not return the key again. BotDojo account, project, flow, index, and release IDs are not exposed.

The external installation ID is unique within the partner. Timestamps have a five-minute tolerance, and each nonce can be used only once.

Create an administrator launch

The partner application server uses the project key returned during provisioning:

POST /api/v1/partners/installations/{installation_id}/admin-launches
Authorization: Bearer {project_api_key}
Content-Type: application/json

Example body:

{
	"subject": "partner-administrator-id",
	"display_name": "Administrator Name",
	"parent_origin": "https://admin.partner.example"
}

The installation, active project key, and parent origin must match. The response contains the configured application URL with a single-use launch code that expires after 60 seconds.

The embedded application exchanges the code on the BotDojo application origin:

POST /api/v1/public/partner-admin-launches/exchange
Content-Type: application/json

{"code":"..."}

The response contains the installation's account, project, application resource manifest, and a short-lived administrator token. The embedded application uses that token with the standard BotDojo project API and includes the registered parent origin in X-BotDojo-Parent-Iframe on every request.

The server revalidates the installation, current project key, account, project, and parent origin before accepting the token. It cannot be used for a different account or project. The permanent project API key remains in the partner module and is never returned to the iframe.

Revoke an installation

DELETE /api/v1/partners/installations/{installation_id}
Authorization: Bearer {project_api_key}

Revocation archives the installation's project key and invokes the configured application adapter's cleanup behavior.