Third-party identity
POST /v1/auth/credentials/provider/:provider — binding a third-party account as a sign-in method.
Binding a third-party identity turns "that me on GitHub" into a key for this account. It is a different endpoint from the third-party sign-in callback, and the authorization model is entirely different: the sign-in endpoint is anonymous, the binding endpoint requires a session and step-up.
Request
POST /v1/auth/credentials/provider/:provider, where provider is github or microsoft.
| Parameter | Type | Required | Notes |
|---|---|---|---|
code | string | ✅ | Authorization code from the provider callback, 1–1024 chars |
redirect_uri | string | ✅ | Exactly the address used when the binding started |
code_verifier | string | ✅ | Raw PKCE value, 43–128 chars |
{ "success": true, "changed": true, "credential": { "id": "cred_...", "type": "oauth", "provider": "github" } }| Field | Notes |
|---|---|
changed | Whether a credential was actually added; re-binding the same identity returns false |
credential | The resulting credential, shaped as in the credential management overview |
code_verifier is mandatory here
Without it in a sign-in, the worst case is login CSRF. Without it here, an attacker can inject their own authorization code into the victim's browser and leave a backdoor on the victim's account that they fully control. PKCE is the only thing proving "this code came from the browser that started the binding".
Behaviour
| Rule | Notes |
|---|---|
| Never creates an account | The identity is attached to the account of the current session |
| Never issues tokens | Binding is not sign-in; no access token is produced |
| Idempotent | If the identity is already bound to this account, the existing credential is returned with changed: false |
| Audit | Written only when changed: true, as provider.bind |
Provider directory
The information needed before binding comes from two endpoints, described in the credential management overview:
GET /v1/auth/providers: public directory for rendering buttons on the sign-in page;GET /v1/auth/credentials/providers: adds alinkedfield for the console's security settings page.
Related
- Signing in with a third-party account: Third-party callback
- Unlinking:
DELETE /credentials/:credentialIdin the credential management overview