Start signing in with a provider

Start signing in with a provider, e.g. when someone clicks "Sign in with Google". The response is the URL to send them to; they come back to redirectUrl, which completes the sign-in. See signing in with a provider for the whole flow.

The API token needs the authenticate permission for the group. Don't send an identity token: an identity that's already logged in can't sign in again (use linking instead).

clientVerifierHash is the SHA-256 hash, in hexadecimal, of a random value your app keeps until the person comes back. Only the browser that started a sign-in can complete it, so a leaked return URL is no use to anyone else. The JS SDK does this for you.

POST https://api.jsonpad.io/identities/oauth/:provider/start

Example

12345678

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

Parameters

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

Request headers

required
x-api-tokenstringYour API token.

Request body

{group: "sample-group"
redirectUrl: "https://myapp.com/auth/callback"
clientVerifierHash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

optional
groupstringThe identity group. Leave this out for identities with no group.
required
redirectUrlstringThe page in your app the person comes back to. It must be one of the identity group's redirect URLs, compared exactly.
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 sign-in has to be completed 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:04.277Z"
}

Response headers

No response headers

2026-09-17