Use this route when your agent cannot install the CLI or register an MCP connector. Device authorisation uses HTTPS; it does not require a shell, a package installation or MCP. The human still signs in and separately approves access.

Check the environment

You need authenticated HTTPS requests, a way to show the human an approval link and code, and persistent secure credential storage. A vault, harness secret store, OS keychain or protected CLI credential file qualifies. A temporary runtime backed by a persistent vault is supported.

Check that you can save the returned credential directly into that store and use it in later authorised sessions without exposing it. If a requirement is missing, name that requirement before stopping. Missing MCP registration alone does not make the environment incompatible.

Start a device grant

Send an unauthenticated request to the API:

code

POST https://api.scrollport.com/v1/auth/device
content-type: application/json
 
{
  "client_name": "your-agent-name",
  "access_method": "api",
  "scopes": ["discover", "inspect", "run", "wallet", "apps", "files"]
}

The response includes verification_uri_complete, user_code, device_code, interval and expires_in. Show both the link and code to the human. They check the matching code, sign in and separately select Authorise agent. A device request or sign-in alone grants no access.

Poll for approval

Poll the token endpoint using the device_code and the returned interval:

code

POST https://api.scrollport.com/v1/auth/token
content-type: application/json
 
{ "device_code": "<device_code>" }

authorization_pending means the human has not decided yet. Poll no faster than interval seconds; on slow_down, use the longer returned interval. Stop on access_denied or expired_token. Do not create a second grant just because the first poll is pending. After approval, the token response returns api_key exactly once: store it directly in the runtime's secret store, never print or log it, and discard the device code.

Check the grant

Make a free wallet request with the key injected from the secret store:

code

GET https://api.scrollport.com/v1/wallet
Authorization: Bearer <stored credential>

A successful response confirms authenticated access without running a paid tool. Use the same stored credential for the nine HTTP control operations; native MCP tools do not need to appear in the agent's tool list.

Standard agent permissions

The fixed grant is discover, inspect, run, wallet, apps and files. It allows paid tool use under workspace spending controls and reading, uploading and permanently deleting workspace files. It cannot be narrowed to read-only access and never includes sys-admin. A free wallet check does not narrow the grant.

Keep credentials out of chat, URLs, logs and committed files. See credentials and configuration for storage and revocation.