Start provider sign-in
Starts the provider’s sign-in flow. For browser-based providers the response carries a URL for the client to open; completion is reported on the returned auth session status and reflected in the provider’s authState. Credentials are stored so another user on the machine cannot read them. Expired credentials prompt re-authorisation via this same operation — they never silently fail.
The body chooses between the two methods. key carries a key the person typed and answers once the host has probed it against the provider’s own API — so this call is as slow as that probe, and a rejected key is never stored. subscription runs the provider’s OAuth flow inside the host and answers as soon as there is a URL to open, leaving the flow running; the client polls getProviderAuth for its outcome. A sign-in already in flight for this provider is never started a second time: a subscription request is answered with the attempt as it stands, and a key request is refused with 409 — its outcome would otherwise overwrite the running flow’s record.
A sign-in that FAILED is a 202 whose status is failed, not an error response: the request was served, the sign-in was not.
Path Parameters
The provider's name.
128^[a-z0-9][a-z0-9-]*$Body
Which sign-in to start, and the key when the person typed one. An absent body is the same as {"method": "key"} with no key, which is refused — a key method needs a key.
key stores a key the person typed, after probing it. It is the default because a subscription sign-in launches a browser or a device-code poll, and that must never be a surprise.
key, subscription The provider API key, required for method key and refused for any other. It is a secret in transit and at rest: the host stores it in the OS keychain, never in its store, its logs, any transcript, or any error message this operation can answer with.
4096Response
Sign-in started, finished, or failed. When browserUrl is present, open it to complete the flow.
A sign-in flow, in flight or finished. When browserUrl is present the client opens it; completion is reflected in the provider's authState.
pending means the host is still driving the flow — poll getProviderAuth. complete means a credential was probed and stored. failed means this attempt is over and message says why; nothing was stored.
pending, complete, failed URL the user opens to complete a browser-based flow.
Human-readable instruction, for example a device code to enter — and, on a failed status, why the sign-in failed. It never carries the key or token itself.
1024When the pending flow expires.

