Operator Api
Launch
Generate a launch URL for an operator user.
Launch
Generate single-use Mini App launch URL from operator backend.
Path
POST /api/operator/launch
Required scope: launch:write
Request body
{
"external_user_id": "operator-user-123",
"display_name": "Rina",
"locale": "id",
"metadata": {}
}
| Field | Type | Requirement | Notes |
|---|---|---|---|
external_user_id | string | Required | Non-empty, stable ID in the operator system. |
display_name | string | Optional | Stored as the latest display-name snapshot. |
locale | string | Optional | Stored as the user's locale preference. Use a Mini App-supported locale such as en, id, es, or zh-CN. |
metadata | object | Optional | Merged into existing operator-user metadata. Defaults to no metadata changes. |
host | string | Optional | Environment-specific launch host. Omit unless the Provider assigned one. |
Optional host
host is the active domain or subdomain allowed for Mini App operations. The allowed value can differ between deployment environments.
Unless your Provider explicitly assigns a host, omit this field. OpenPoly will resolve the active allowed host for the authenticated operator and current environment. Sending a host that is not active and allowed for that operator returns INVALID_OPERATOR_HOST.
Response
{
"launch_url": "https://your-launch-host/launch?token=...",
"expires_at": "2026-06-18T00:01:00.000Z",
"operator_user": {
"id": 1,
"external_user_id": "operator-user-123",
"status": "active"
}
}
Contract rules
- Launch token is single-use.
- Token TTL is runtime-configured, defaults to 60 seconds, and is never shorter than 30 seconds.
external_user_idmust be stable per operator user.- Operator user is upserted on launch request.
- If
hostis provided, it must match an active host configured for the authenticated operator. - Repeated launch calls may issue new launch tokens for same operator user.
Integration rules
- Call this endpoint only from operator backend.
- Redirect or hand off returned
launch_urlto operator client. - Never generate or inspect launch token on client.