Authorization

Start a browser client authorization

First step of connecting a first-party client (the VS Code extension) to an account. Public: the client has no credential yet.

The client generates a PKCE verifier, sends its SHA-256 (challenge, base64url — only S256 is accepted), and gets back a code plus a display code. It then opens the consent page with ?code=… and shows display to the person, who must check that the page shows the same 8 characters before approving. That comparison is what makes a forged consent link fail, because a forged link carries the attacker's code.

The slot created here is empty. It is the client — not the browser — that creates it, and approval can only fill a slot that already exists and is not yet approved. Without that, whoever learned the code could approve it with their own account and the client would end up holding a key to someone else's account.

The requested scopes/resources are parsed once, here, and everything downstream reads them from the stored grant, never from a parameter. Expires in 10 minutes.

post/v2/account/authorize/start

Request body

client_id'vscode' required
redirect_uristring required

Must be registered for the client. vscode accepts vscode://squarecloud.squarecloud/callback and http://127.0.0.1:<port>/callback.

scopesstring[] required
resourcesstring[]

Optional. Restricts the resulting key to these applications/databases.

challengestring required

base64url(SHA-256(verifier)).

challenge_method'S256'

Optional; S256 is the only value.

Response

Authorization started. Open the consent page with code and show display to the person.

status'success' required

Changes