---
title: "Start a browser client authorization"
method: POST
path: "/v2/account/authorize/start"
tags: ["Authorization"]
---

# Start a browser client authorization

`POST /v2/account/authorize/start`

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.

## Request body

- object
  - `client_id` 'vscode', required
  - `redirect_uri` string, required — Must be registered for the client. `vscode` accepts `vscode://squarecloud.squarecloud/callback` and `http://127.0.0.1:<port>/callback`.
  - `scopes` string[], required
  - `resources` string[] — Optional. Restricts the resulting key to these applications/databases.
  - `challenge` string, required — base64url(SHA-256(verifier)).
  - `challenge_method` 'S256' — Optional; S256 is the only value.

## Response `200`

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

- object
  - `status` 'success', required
  - `response` object, required
    - `code` string, required
    - `display` string, required
    - `expires_in` integer, required

## Other responses

- `400` — `UNKNOWN_CLIENT`, `INVALID_REDIRECT_URI`, `INVALID_SCOPES`, `INVALID_RESOURCES`, `INVALID_CHALLENGE`, `INVALID_JSON_BODY` or `UNKNOWN_IP`.
- `413` — Body over 4 KB.
- `429` — The endpoint enforces its own rate limit and the caller hit the cooldown.
- `500` — An unexpected error occurred while processing the request.

---

[API](https://skmtc.dev/squarecloud/apis/square-cloud-api.md) · [All operations](https://skmtc.dev/squarecloud/apis/square-cloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/squarecloud/square-cloud-api/revisions/54b7733a6b95/schema)