Signing in
The console authenticates with an interactive session, not with an API key. The door is at console.phoneuse.com, and it takes an email address and a password, or Google. Signing up confirms the address with a six digit code and creates your organization on the way in, so there is no separate step for it. Your session is the credential for every console screen. An API key can do much of what a session does, but not everything: see Two kinds of credential.The screens that exist
In the sidebar, Keys, MCP, Webhooks and Quickstart sit together
under Developers.
A device you bought appears in the console’s device list, and in
GET /v1/devices, once the order settles. Open it to reach /devices/:id.
Buy and drive a device walks the whole loop
through these screens, with the API equivalent of each step beside it.
The Control block
/devices/:id carries a Control block, and it is the part worth explaining
before you use it.
- The screen is live. A cloud phone that declares
stream: "webrtc"is shown as live video, throughPOST /v1/devices/{deviceId}/live-session. That route needs your org to hold the phone’s lease: without one it answers409 lease_requiredand takes no lease itself. When the console gets that answer, it takes a lease for your org and asks again; if that take is refused, there is no live video. A device withoutstream: "webrtc"shows the current still frame. Nothing records a session as video. See What PhoneUse is not. - Tapping the screen acts under your org’s lease. A device holds one lease
at a time, across every org, and that has not changed: it is what keeps two
organisations off one phone, and what the meter runs on. Inside your org the
lease is shared. If an agent’s run holds it, your taps go straight to the
phone under that lease and the run keeps going; the agent is told what you
did on its next result and is never stopped by it. If nobody holds it, your
first tap takes a lease for you, for ten minutes, and keeps it alive while
you keep driving. The gesture is the browser spelling of
POST /v1/devices/{deviceId}/actions, and the response says which lease it ran under and whether it was somebody else’s (coDriving). - The picture is the target. Click the image where you want the device tapped. The console converts where you clicked into the normalized grid described below. You never type a pixel.
- Who else is on the phone comes from one read,
GET /v1/devices/{deviceId}/driving: the run on the device, whose lease it is, and who else acted in the last minute. The console shows it only while somebody else is on the phone. Pause agentandStop runare the only interruptions, and both are yours to choose:POST /v1/runs/{runId}/pauseshuts the agent’s channels until you pressResume agent, andPOST /v1/runs/{runId}/cancelends the run. Acting on the screen interrupts nothing.- A lease you took yourself bills until it expires. Nothing watches for
idleness. It expires ten minutes after your last gesture kept it alive, or
you can give it back with
DELETE /v1/devices/{deviceId}/lease.
A control that cannot work is disabled, and says why
Devices differ, and the console does not pretend otherwise. A control the device in front of you cannot perform is drawn disabled with its reason attached, for exampleAction not supported on this device.
That is the same fact the API states as capabilities, and it is worth reading
directly before you plan anything. Part of a cloud phone’s actions block:
uiTree: false), so its screen is read from
screenshots. That is the ordinary case, not a fault. Read your own device’s
block rather than carrying this one forward. Capabilities explains every field.
Coordinates are normalized, everywhere
Both axes run 0 to 1000 whatever the real screen is, with the origin at the top left in the current orientation. The device states it ascoordSpace: { "width": 1000, "height": 1000 }.
This is why clicking a picture works. A click at one quarter across and three
quarters down a rendered image committed on a real device today at x=247,
y=749. Callers never speak device pixels, and neither does the console.
What has no screen
Two surfaces are live over HTTP and have no console face at all. Do not go looking for a screen; use the API.Two kinds of credential
An API key is refused from a browser origin. Put one in front end JavaScript
and the request comes back
403 with the code
api_key_from_browser_origin, whatever the key’s scopes are. The refusal is
explicit rather than vague, because the audience is a developer who has just
shipped a key into a browser bundle and needs to know it.
Keys are for servers. Browsers get a session. If you want a browser to drive a
device, the console already does that with the session it holds.
Buying is narrower still. A monthly phone needs an admin’s session, or an API
key that holds orders:place, which only an admin can mint or approve. Either
way a person still pays on the Checkout page. A member cannot buy, and per
minute phones are started from an admin’s session only. See
Authentication.
Managing keys is the other way round. Either role does it, from a signed in
session only, and the bound is ownership rather than seniority: a member
mints keys and then rotates, renews and revokes the ones they minted, while an
admin can act on any key in the org. None of the four asks you to
reauthenticate: a signed in session is the whole of what minting a key
requires.
Where to go next
Buy and drive a device
The whole loop, in the console and over the API, with real readings.
Authentication
The eight scopes, and how a key is narrowed to a subset of your devices.