Link a provider account

Start linking a provider account to the current identity, so it can sign in with that account as well as the way it does now. This works like starting a sign-in: send the person to the URL in the response, then finish it on the return page.

The API token needs the update-self permission for the identity's group. If another identity is already linked to that account, finishing it fails with IDENTITY_PROVIDER_ALREADY_LINKED (20021).

POST https://api.jsonpad.io/identities/self/providers/:provider/start

Example

123456789

curl https://api.jsonpad.io/identities/self/providers/google/start \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>" \
  -H "x-identity-group: players" \
  -H "x-identity-token: <IDENTITY TOKEN>" \
  -d '{
        "redirectUrl": "https://myapp.com/settings/accounts",
        "clientVerifierHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
      }'

Parameters

required
providerstringgoogle, github, apple, microsoft, discord or facebook, and enabled for the identity's group.

Request headers

required
x-api-tokenstringYour API token.
required
x-identity-tokenstringAn identity token.
required
x-identity-groupstringAn identity group.

Request body

{redirectUrl: "https://myapp.com/settings/accounts"
clientVerifierHash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

required
redirectUrlstringThe page the person comes back to, which must be one of the identity group's redirect URLs.
required
clientVerifierHashstring64 hexadecimal characters: the SHA-256 hash of the verifier your app keeps for the return page.

Response body

200 OK

Send the browser to url. The link has to be finished before expiresAt, 10 minutes later.

{url: "https://accounts.google.com/o/oauth2/v2/auth?response_type=code&client_id=...&state=kP1s2JNS2v5HcwH..."
expiresAt: "2026-09-18T20:42:07.439Z"
}

Response headers

No response headers

2026-09-17