A valid request URL is required to generate request examples{
"installation": {
"installationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requestKey": "<string>",
"appId": "<string>",
"buildId": "<string>",
"name": "<string>",
"packageName": "<string>",
"versionName": "<string>",
"deviceId": "<string>",
"scopeId": "user_0",
"status": "queued",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"receiptId": "<string>",
"reasonCode": "<string>",
"verifiedAt": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}Install an app
Managed Android app store. Requires apps:read, devices:read, devices:act, devices:lease. Catalogue sources stay on the server. Accepted installs persist before the worker uses native action governance, leases and receipts. After uncertain dispatch only original-receipt and fresh inventory reads run; no automatic reinstall. Installed requires verified exact phone, primary profile, package and catalogue version. All history is tenant/device scoped; activeItems repeats every held installation on each bounded page. An uncertain confirmation result re-checks after 10 s, 30 s, 2 min, 10 min and 30 min; the next uncertain result, or 60 inventory refreshes without proof, stops automatic checks with status unconfirmed and reasonCode needs_review: the phone stays held and PhoneUse staff are alerted once. A phone installs one app at a time: a direct install is refused with 409 request_in_progress (no field) while the phone has an unfinished installation or any app waiting in its install queue. To wait in line instead, use POST /v1/app-store/queue. Request keys are one namespace across direct installs and the queue: a key that started from the queue replays its installation here; a key still waiting in, or removed from, a queue is refused with 409 idempotency_conflict (query it with GET /v1/app-store/queue/by-request/). While the phone is held by another operation at that moment (for example it is being released), the request is refused with 429 rate_limited, field deviceId and a Retry-After of about 5 seconds; nothing is created, so retry with the same request key.
A valid request URL is required to generate request examples{
"installation": {
"installationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requestKey": "<string>",
"appId": "<string>",
"buildId": "<string>",
"name": "<string>",
"packageName": "<string>",
"versionName": "<string>",
"deviceId": "<string>",
"scopeId": "user_0",
"status": "queued",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"receiptId": "<string>",
"reasonCode": "<string>",
"verifiedAt": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}Authorizations
The control surface credential. Send Authorization: Bearer <token>.
Two kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning pbk_ or puk_ is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.
Both resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.
Scopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from tools/list rather than refused mid gesture.
Headers
The install request key, one per install request. It must have the form store.v2.<24 hex characters>., matching ^store.v2.[a-f0-9]{24}.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ . The 24 hex characters bind the key to who is asking and to what they ask for. Work them out like this: (1) make a text value who = JSON.stringify([orgId, subject]), where subject is the signed-in person's userId, or the apiKeyId when an API key makes the call (apiKeyId is the id field of GET /v1/api-keys/current, not its keyId); (2) make a text value payload = JSON.stringify([who, deviceId, scopeId, appId, buildId]), where who is the text from step 1 (so it is quoted inside the list), deviceId, scopeId and appId and buildId are the values you send in the body, and scopeId is user_0; (3) take the sha256 of payload as lowercase hex and keep its first 24 characters; (4) join them as store.v2.<those 24 characters>.. Worked example: orgId org_example, apiKeyId key_example, deviceId device_example, scopeId user_0, appId telegram, buildId v12.10.1 and UUID 6f1c2a52-3b6e-4d0c-9a57-0d3c8f0b1e11 give store.v2.e22bfe7f226ee0e308ab9fe3.6f1c2a52-3b6e-4d0c-9a57-0d3c8f0b1e11 . A key built for another account, phone, app or build is refused with 400. Keep the key: if the answer is lost, send the same body with the same key to get the same installation back, or read it with GET /v1/app-store/installations/by-request/{requestKey}. A second key is a new request and is refused while the phone is held. [blocked]
^store\.v2\.[a-f0-9]{24}\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"store.v2.e22bfe7f226ee0e308ab9fe3.6f1c2a52-3b6e-4d0c-9a57-0d3c8f0b1e11"
Body
Trusted catalogue build and confirmed primary Android target. Arbitrary URLs, APK bytes, leases and provider parameters are refused.