Skip to main content
POST
Start provider sign-in

Path Parameters

name
string
required

The provider's name.

Maximum string length: 128
Pattern: ^[a-z0-9][a-z0-9-]*$

Body

application/json

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.

method
enum<string>
default: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.

Available options:
key,
subscription
key
string

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.

Maximum string length: 4096

Response

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.

status
enum<string>
required

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.

Available options:
pending,
complete,
failed
browserUrl
string<uri>

URL the user opens to complete a browser-based flow.

message
string

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.

Maximum string length: 1024
expiresAt
string<date-time>

When the pending flow expires.