Kanorio
Kanorio 開發者

API 參考

Auth

Customer API: GET /auth/protection, POST /auth/challenge, POST /auth/verify, …

此頁只有英文版。API 參考、Webhook 事件及變更紀錄維持英文，與程式碼中的欄位名稱、錯誤碼一致。
Base URL https://{site}/api/v1/customerErrorsPagination

Get the bot check to pass before requesting a login code

GET/auth/protection
betaNo auth

Response 200

  • provider"kanorio" | "turnstile" | "recaptcha" | "hcaptcha"required
  • entry"forms" | "customer_login"required
  • altchaobject

    Built-in proof-of-work challenge (provider kanorio only).

  • altcha.algorithmstringrequired
  • altcha.challengestringrequired
  • altcha.maxnumberinteger
  • altcha.saltstringrequired
  • altcha.signaturestringrequired
  • siteKeystring

    Widget site key (third-party providers).

  • actionstring

    Pass this as the widget action; the server checks it.

  • cDatastring | null

    Turnstile cData to pass to the widget; null for other providers.

  • recaptchaVersion"v2" | "v3" | null
  • visibleboolean

    When true, show the check to the visitor instead of running it silently (the site is seeing unusual sign-in volume).

  • uploadTokenstring

    Forms with a third-party provider only: send this as _tk (with _ctx set to the form id) when requesting file upload tickets. The widget token is single-use, so it is checked on submit instead.

Errors

  • WEBSITE_NOT_FOUND 404
  • RATE_LIMITED 429
curl -X GET "https://{site}/api/v1/customer/auth/protection"

Request a login code / magic link by email

POST/auth/challenge
betaNo auth

Request body

  • emailstringrequired
  • localestring
  • returnTostring
  • _hpstring

    Honeypot. Send an empty string; any value marks the request as automated.

  • _wpstring

    Second honeypot. Send an empty string.

  • _costring

    Third honeypot. Send an empty string.

  • _tsinteger

    When the form was rendered, in Unix milliseconds.

  • _tkstring

    Built-in bot check: the solved ALTCHA payload for the challenge (provider kanorio).

  • _ctxstring

    What the built-in challenge was issued for: the form id, or customer-login:{siteId}.

  • captchaTokenstring

    Third-party bot check: the token from the provider's widget (provider turnstile, recaptcha or hcaptcha).

Errors

  • INVALID_EMAIL 400
  • BOT_PROTECTION_FAILED 403
  • WEBSITE_NOT_FOUND 404
  • SHARED_SENDER_PAUSED 503
curl -X POST "https://{site}/api/v1/customer/auth/challenge" \
  -H "Content-Type: application/json" \
  -d '{}'

Exchange a code, magic-link token or social sign-in handoff ticket for a Bearer session

POST/auth/verify
betaNo auth

Request body

  • method"code"required
  • emailstringrequired
  • codestringrequired

Response 200

  • sessionTokenstringrequired
  • tokenType"Bearer"required
  • channel"bearer"required
  • expiresAtstringrequired
  • contactIdstringrequired
  • returnTostring | null

Errors

  • INVALID_CODE 400
  • ACCOUNT_BLOCKED 422
  • EMAIL_NOT_VERIFIED 422
  • METHOD_DISABLED 422
curl -X POST "https://{site}/api/v1/customer/auth/verify" \
  -H "Content-Type: application/json" \
  -d '{}'

Start a social sign-in (Google) and get the provider URL to redirect to

POST/auth/oauth/start
betaNo auth

Request body

  • method"google"required

    A social sign-in method the site has enabled (see `customerAccess.methods` on the site).

  • returnTostring

    Same-site path to return to after sign-in.

  • localestring
  • baseUrlstring

    Origin of the page that hosts the sign-in UI. Must be one of the site's allowed origins; the handoff ticket is sent back there.

Response 200

  • urlstringrequired

    Redirect the browser here. The provider sends it back to your page with `?handoff=` to exchange at `/auth/verify`.

Errors

  • METHOD_DISABLED 422
  • RATE_LIMITED 429
curl -X POST "https://{site}/api/v1/customer/auth/oauth/start" \
  -H "Content-Type: application/json" \
  -d '{}'

Get WebAuthn request options to sign in with a passkey

POST/auth/passkey/options
betaNo auth

Request body

  • originstring

    Origin the WebAuthn ceremony runs on. Only `localhost` origins are honoured; production always uses the site's primary domain.

Response 200

  • optionsobjectrequired

    `PublicKeyCredentialRequestOptionsJSON` for `navigator.credentials.get()`.

  • challengeIdstringrequired

Errors

  • METHOD_DISABLED 422
  • RATE_LIMITED 429
curl -X POST "https://{site}/api/v1/customer/auth/passkey/options" \
  -H "Content-Type: application/json" \
  -d '{}'

Verify a passkey assertion and get a Bearer session

POST/auth/passkey/verify
betaNo auth

Request body

  • challengeIdstringrequired
  • responseobjectrequired

    `AuthenticationResponseJSON` from the browser.

  • returnTostring
  • localestring

Response 200

  • sessionTokenstringrequired
  • tokenType"Bearer"required
  • channel"bearer"required
  • expiresAtstringrequired
  • contactIdstringrequired
  • returnTostring | null

Errors

  • VERIFY_FAILED 422
  • CHALLENGE_EXPIRED 422
  • ACCOUNT_BLOCKED 422
  • RATE_LIMITED 429
curl -X POST "https://{site}/api/v1/customer/auth/passkey/verify" \
  -H "Content-Type: application/json" \
  -d '{}'