Starts a server-side link ceremony and returns the provider
authorization URL to send the user to. It does not accept a
provider token or identity assertion: the backend owns the
account-linking decision, and a client-supplied assertion must never
determine who owns an account.
The existing provider callback completes the ceremony. A ceremony is
marked as a link and is claimed by a single conditional update, so a
link ceremony can never be redeemed as a sign-in and a sign-in
ceremony can never be redeemed as an explicit account-settings link.
The ceremony is bound to the already authenticated target account and
does not choose that target from the provider email. An identity
already belonging to another account is refused 409 and is never
transferred. Linking an identity already linked to the caller is
idempotent. Separately, ordinary provider sign-in may attach a
previously unseen identity when the provider verifies the same
normalized account email.
Requires authentication within the last 15 minutes.
Header Parameters
X-CSRF-TokenRequired
string·min 43·max 43
Session-bound CSRF token. It must exactly match the
__Host-assign_csrf cookie sent with the request.
Request Body
application/json
providerRequired
string
Values
googlegithubapple
Responses
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
authorization_urlRequired
string <uri>
The provider authorization URL to send the user to. The ceremony
state is minted server-side and bound to the calling user and
session; the client neither generates nor modifies it.
expires_atRequired
string <date-time>
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
errorRequired
object
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
errorRequired
object
errorRequired
object
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
errorRequired
object
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
Retry-After
integer·min 1
Seconds until the client may retry.
errorRequired
object
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
errorRequired
object
Retry-After
integer·min 0
Delay in seconds before retrying, when an expected maintenance end is known.
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
