From b899e9597aeec4728a238957d19ef4d9ec433631 Mon Sep 17 00:00:00 2001 From: Tamal Anwar Chowdhury Date: Wed, 17 Jun 2026 19:19:17 +0600 Subject: [PATCH] feat: Passkeys doc --- .../about-auth/about-authentication.mdx | 37 +- .../about-auth/authentication-methods.mdx | 6 +- .../email-deliverability.mdx | 2 +- .../authentication-methods/passkeys.mdx | 347 ++++++++++++++++++ .../sms-deliverability.mdx | 2 +- 5 files changed, 372 insertions(+), 22 deletions(-) create mode 100644 src/content/docs/authenticate/authentication-methods/passkeys.mdx diff --git a/src/content/docs/authenticate/about-auth/about-authentication.mdx b/src/content/docs/authenticate/about-auth/about-authentication.mdx index 0eb5d1fa1..c7b9d20b8 100644 --- a/src/content/docs/authenticate/about-auth/about-authentication.mdx +++ b/src/content/docs/authenticate/about-auth/about-authentication.mdx @@ -12,17 +12,14 @@ relatedArticles: app_context: - m: settings s: authentication -description: >- - Learn about Kinde's authentication methods including password, passwordless, - social sign-in, and enterprise connections. +description: "Discover Kinde authentication options from passwordless and passkeys to social, enterprise SSO, and multi-domain session sharing." featured: false deprecated: false -ai_summary: >- - Comprehensive overview of Kinde's authentication methods including password, - passwordless, social sign-in, and enterprise connections with multi-domain - support. +ai_summary: "Overview of authentication in Kinde and the sign-up and sign-in options available to end users. Lists supported methods including self-sign-up and invitation-only access, passwordless OTP enabled by default in new businesses, email and username password authentication, phone and WhatsApp authentication, passkeys for sign-in, social connections such as Google and Apple, enterprise connections such as Microsoft Entra ID and Google Workspace, and custom OAuth 2.0 and SAML providers. Explains that authentication is configured per environment and can differ per application. Covers multi-domain authentication across subdomains on the same primary domain, including using prompt=none in the auth URL for seamless session switching between sites. Warns that production social and third-party auth requires your own Client ID and Client Secret to avoid Kinde proxy rate limits and Apple SSO identity issues. Includes a get-started checklist for setting up authentication, adding social sign-in, and enabling multi-factor authentication. Intended for developers and product managers planning Kinde authentication." topics: - authenticate + - sign-in + - multi-domain-auth sdk: [] languages: [] audience: @@ -30,28 +27,32 @@ audience: - product-manager complexity: beginner keywords: - - authentication + - authentication methods - sign up - sign in - - password - passwordless - - social login - - enterprise - - SSO -updated: 2025-01-16 + - passkeys + - social sign-in + - enterprise SSO + - multi-domain authentication +updated: 2026-06-17 --- Kinde makes authentication easy by providing a range of methods to choose from. Allow your users to sign up or sign in: -- [by invitation only](/authenticate/custom-configurations/disable-sign-up/) - using self-sign-up (default) -- [with a password](/authenticate/authentication-methods/password-authentication/) +- [by invitation only](/authenticate/custom-configurations/disable-sign-up/) - [passwordless](/authenticate/authentication-methods/passwordless-authentication/) (Applied by default in all new Kinde businesses) -- with a [phone number](/authenticate/authentication-methods/phone-authentication/) -- with a range of [social sign in options](/authenticate/social-sign-in/add-social-sign-in/), like Google, Apple, Slack, and more -- via [enterprise connections](/authenticate/enterprise-connections/about-enterprise-connections/) such as Cloudflare or SAML +- with [password](/authenticate/authentication-methods/password-authentication/) (email or username) +- with [phone number](/authenticate/authentication-methods/phone-authentication/) +- with [WhatsApp](/authenticate/authentication-methods/whatsapp-authentication/) +- with [passkey](/authenticate/authentication-methods/passkeys/) (sign-in only) +- [social connections](/authenticate/social-sign-in/add-social-sign-in/), like Google, Apple, Slack, and more +- [enterprise connections](/authenticate/enterprise-connections/about-enterprise-connections/), like Microsoft Entra ID, Google Workspace, and more +- [Custom OAuth 2.0 connections](/authenticate/custom-configurations/custom-oauth2-connection/) +- [Custom SAML connections](/authenticate/enterprise-connections/custom-saml/) Authentication can be set per environment, and can be changed for different applications, e.g. your production web app and mobile app can have different authentication requirements. diff --git a/src/content/docs/authenticate/about-auth/authentication-methods.mdx b/src/content/docs/authenticate/about-auth/authentication-methods.mdx index 4fed28e9c..219ab917f 100644 --- a/src/content/docs/authenticate/about-auth/authentication-methods.mdx +++ b/src/content/docs/authenticate/about-auth/authentication-methods.mdx @@ -126,6 +126,8 @@ Kinde supports the use of [Microsoft Entra ID](/authenticate/enterprise-connect You can add any OAuth 2.0 compatible identity provider as an authentication method. You should check compatibility thoroughly and test these types of connections in a non-production environment. Here are the instructions for getting set up with [custom OAuth 2.0](/authenticate/custom-configurations/custom-oauth2-connection/). Note there may be variations in field names and terms depending on the provider you use. -## Passkeys (coming soon) +## Passkeys -Passkey authentication is not yet available in Kinde. It is currently in development and on the [Kinde roadmap](https://updates.kinde.com/board/secure-passkey-authentication). You can follow progress and vote on the roadmap to signal interest. +Passkeys are a passwordless sign-in method based on the Web Authentication (WebAuthn) standard. Users authenticate with device biometrics (Face ID, Touch ID, Windows Hello), a platform authenticator, or a FIDO2 security key — no password required. + +See [Passkeys](/authenticate/authentication-methods/passkeys/) for setup, policies, and user experience details. diff --git a/src/content/docs/authenticate/authentication-methods/email-deliverability.mdx b/src/content/docs/authenticate/authentication-methods/email-deliverability.mdx index 51b9779ac..cdc25f8b7 100644 --- a/src/content/docs/authenticate/authentication-methods/email-deliverability.mdx +++ b/src/content/docs/authenticate/authentication-methods/email-deliverability.mdx @@ -2,7 +2,7 @@ page_id: c4182a6d-64ca-4c82-ba33-e5fc5d8b8cad title: Email deliverability in Kinde sidebar: - order: 8 + order: 9 relatedArticles: - 0222489b-3478-48a7-a5c9-c99c6044f0e9 - 90134c89-16e4-4981-b988-b0cb4f1722c5 diff --git a/src/content/docs/authenticate/authentication-methods/passkeys.mdx b/src/content/docs/authenticate/authentication-methods/passkeys.mdx new file mode 100644 index 000000000..4f47c16ad --- /dev/null +++ b/src/content/docs/authenticate/authentication-methods/passkeys.mdx @@ -0,0 +1,347 @@ +--- +page_id: df85ffe2-19aa-4f3a-b94e-ddd86452ef79 +title: Enable Passkeys to sign in users +sidebar: + order: 8 + label: Passkeys +relatedArticles: + - 26e55a64-13dd-4c7b-b9ad-e7595903ddc8 + - 720fcdda-daa6-4dff-ad2d-177af555e6bb + - 0145d1ce-564e-4c28-820f-2f126abbfe3a + - 84581694-59d6-4a02-ab8b-c7a2889713d5 +tableOfContents: + maxHeadingLevel: 3 +description: "Enable WebAuthn passkeys in Kinde for passwordless sign-in with biometrics or security keys—policies, API, webhooks, and rollout guidance." +featured: false +deprecated: false +topics: + - authenticate + - authentication-methods + - passkeys +sdk: + - kinde-management-api +languages: + - bash + - json +audience: + - developer + - product-manager + - security-engineer +complexity: intermediate +keywords: + - passkeys + - webauthn + - passwordless sign-in + - fido2 + - passkey policy + - passkey management api + - passkey webhooks + - security key +ai_summary: "Guide to enabling and managing passkey authentication in Kinde using the Web Authentication (WebAuthn) standard. Explains how passkeys complement existing email, passwordless OTP, social, and enterprise auth methods rather than replace them. Covers dashboard setup under Settings and Policies with off, optional, and mandatory environment policies, plus organization-level overrides. Describes the user experience for post-login passkey enrollment, Sign in with passkey on the login page, and passkey management in the account portal and admin Users section. Includes recommended rollout steps from optional to mandatory deployment, passkey configuration via the Kinde Management API for environment and organization settings, passkey.added and passkey.removed webhook events, and technical requirements for domain, HTTPS, RP ID, and browser or device WebAuthn support. Also answers common FAQ on passwords, multiple passkeys, signup behavior, per-application limits, and paid plan requirements. Intended for developers, product managers, and security engineers implementing passwordless passkey sign-in." +updated: 2026-06-17 +--- + + + +Passkeys are a passwordless sign-in method based on the Web Authentication (WebAuthn) standard. Users authenticate with device biometrics (Face ID, Touch ID, Windows Hello), a platform authenticator, or a FIDO2 security key — no password required. + +Passkeys complement your existing auth methods rather than replace them. [Email/password](/authenticate/authentication-methods/password-authentication/), [passwordless OTP](/authenticate/authentication-methods/passwordless-authentication/), [social sign-in](/authenticate/social-sign-in/add-social-sign-in/), and [enterprise connections](/authenticate/enterprise-connections/about-enterprise-connections/) continue to work as before. When enabled, users can sign in with a passkey from the login page, and credential users can be prompted to register one after sign-in. + +![passkey default button](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/ed8376ed-4d56-4aee-9720-f0ded25fe800/socialsharingimage) + +## Enable passkeys in Kinde + +1. Go to your Kinde dashboard > **Settings > Policies**. +2. Scroll down to the **Passkeys** section. +3. Select **Optional** or **Mandatory** to enable passkeys. +4. Select **Save**. + +This sets the default passkey policy for the entire environment. + +### Organization override + +You can override the default passkey policy for an organization. + +1. Go to your Kinde dashboard > **Organizations**, and select the organization you want to configure. +2. Select **Policies**. +3. Under **Passkeys**, enable **Override environment passkey settings**. +4. From the dropdown menu, choose **Off**, **Optional**, or **Mandatory** for that organization. +5. Select **Save**. + +When you configure an org override, the UI shows the current environment default. + +### Passkey policies + +Passkeys are controlled by a **policy** with three values: + +| Policy | Behavior | +| --- | --- | +| **`off`** | Passkeys are disabled. No sign-in button, no setup prompts, no account portal passkey management. | +| **`optional`** | Passkeys are enabled. Users see **Sign in with passkey** on login. After credentials sign-in or registration, users without a passkey are prompted to set one up, but can choose **Not now**. | +| **`mandatory`** | Same as optional, except users **must** complete passkey setup before continuing. The skip option is not shown. | + +The default policy for new environments is **`off`**. + +When passkeys are enabled, users can: + +- **Sign in with a passkey** from the login page +- **Register a passkey** after signing in with email/password (or other credentials) +- **Manage passkeys** from the account portal (add, rename, delete) + +Passkeys are stored per user per environment. Each registered passkey is linked to a passkey identity on the user record. + +### Policy resolution + +- **Environment policy** — the default for all organizations in the environment. +- **Organization override** — an organization can override the environment default with its own policy. + +When an organization override is disabled, the organization inherits the environment policy. + +## User experience + +### Post-login passkey setup + +![setup a passkey](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/5709efc9-9b46-4484-b505-863fc1d2b300/socialsharingimage) + +After a user signs in or registers using **credentials** (email/password, username, or phone OTP), Kinde may prompt them to set up a passkey if: + +- Passkeys are enabled for the relevant organization +- The user does not already have a passkey +- Policy is `optional` or `mandatory` +- For `optional` only: the user has not previously chosen **Not now** + +The setup screen explains that the user can use device biometrics or a security key for faster sign-in next time. + +| Policy | Setup screen | +| --- | --- | +| `optional` | **Continue** registers a passkey; **Not now** skips and records the decline | +| `mandatory` | **Continue** only — setup is required to proceed | + +Passkey setup is not triggered after social or enterprise SSO sign-in. + +### Sign in with passkey + +![sign in with passkey button](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/5a554c40-62db-4cbe-214f-1f30834f1e00/socialsharingimage) + +When passkeys are enabled (`optional` or `mandatory`), the login page shows a **Sign in with passkey** button. + +- Shown only on **sign-in**, not sign-up (users need an existing account and a registered passkey). +- Displayed alongside credential and SSO options according to your auth page layout. +- Uses the browser WebAuthn API to perform a challenge–response assertion. + +Users who have never registered a passkey cannot use this button to create an account. + +### Account portal + +Authenticated users can manage passkeys under **Profile** in the account portal when passkeys are enabled: + +- View registered passkeys (name, last sign-in, sign-in count) +- **Add passkey** for the current device or a security key +- Rename a passkey +- Delete a passkey + +Admins can also view a user's passkeys from the **Users** section in the Kinde admin. + +## Recommended rollout + +### Start with optional + +1. Set environment policy to **`optional`**. +2. Confirm **Sign in with passkey** appears on your login page. +3. Sign in with email/password as a test user and complete passkey setup. +4. Sign out and sign back in with the passkey. +5. Subscribe to `passkey.added` / `passkey.removed` webhooks if you need lifecycle visibility. + +### Move to mandatory (if needed) + +Use **`mandatory`** when you want every user who signs in with credentials to register a passkey after first sign-in. Consider: + +- Users on devices without WebAuthn support will be blocked at setup +- Social/SSO-only users are unaffected (they do not currently see the setup prompt) +- Organization overrides let you pilot mandatory policy on a subset of orgs first + +### Disable passkeys + +Set policy to **`off`**. Existing passkey credentials remain stored but are not usable until re-enabled. Users cannot sign in with or manage passkeys while disabled. + +## Configure passkeys via the Management API + +### Environment passkey settings + +| Method | Endpoint | Scope | +| --- | --- | --- | +| `GET` | `/api/v1/passkey` | `read:passkey` | +| `PUT` | `/api/v1/passkey` | `update:passkey` | + +**Get environment settings** + +```bash +GET /api/v1/passkey +Authorization: Bearer {management_api_token} +``` + +Example response: + +```json +{ + "code": "OK", + "message": "Success", + "enabled": true, + "policy": "optional" +} +``` + +**Update environment settings** + +```bash +PUT /api/v1/passkey +Authorization: Bearer {management_api_token} +Content-Type: application/json + +{ + "policy": "optional" +} +``` + +Valid values: `off`, `optional`, `mandatory`. + +Example success response: + +```json +{ + "code": "PASSKEY_SET", + "message": "Passkey settings successfully updated", + "enabled": true, + "policy": "optional" +} +``` + +### Organization passkey settings + +| Method | Endpoint | Scope | +| --- | --- | --- | +| `GET` | `/api/v1/organizations/{org_code}/passkey` | `read:organization_passkey` | +| `PUT` | `/api/v1/organizations/{org_code}/passkey` | `update:organization_passkey` | + +**Get organization settings** + +```bash +GET /api/v1/organizations/org_abc123/passkey +Authorization: Bearer {management_api_token} +``` + +Example response: + +```json +{ + "code": "OK", + "message": "Success", + "enabled": true, + "policy": "mandatory", + "is_override_environment_passkey_settings": true, + "environment_policy": "optional" +} +``` + +**Set an organization override** + +```bash +PUT /api/v1/organizations/org_abc123/passkey +Authorization: Bearer {management_api_token} +Content-Type: application/json + +{ + "policy": "mandatory", + "is_override_environment_passkey_settings": true +} +``` + +**Revert to environment default** + +```bash +PUT /api/v1/organizations/org_abc123/passkey +Authorization: Bearer {management_api_token} +Content-Type: application/json + +{ + "is_override_environment_passkey_settings": false +} +``` + +When reverting, you do not need to send `policy`. The org override row is removed and the environment policy applies. + +See the [Kinde Management API](/kinde-apis/management) for full endpoint reference. + +## Webhooks + +Subscribe to passkey lifecycle events via [Kinde webhooks](/integrate/webhooks/about-webhooks/): + +| Event | When it fires | +| --- | --- | +| `passkey.added` | A user successfully registers a new passkey | +| `passkey.removed` | A passkey is deleted | + +Example payload shape: + +```json +{ + "type": "passkey.added", + "event_id": "event_…", + "timestamp": "2026-06-16T12:00:00Z", + "data": { + "user": { + "id": "kp_…" + }, + "passkey": { + "id": "019abc50-…", + "name": "Passkey 1" + } + } +} +``` + +## Technical details + +Passkeys use the Web Authentication (WebAuthn) standard. + +### Domain and HTTPS + +- The **Relying Party ID (RP ID)** is derived from your Kinde auth domain (hostname without port). +- **HTTPS is required** in production. HTTP is permitted only for `localhost` during local development. +- Your custom auth domain must be correctly configured; passkeys are bound to that domain. + +### Browser and device support + +Users need a browser and device that support WebAuthn. This includes: + +- Modern Chromium, Safari, and Firefox browsers +- Platform authenticators (Touch ID, Face ID, Windows Hello) +- FIDO2 hardware security keys + +## FAQ + +### Do passkeys replace passwords? + +No. Passkeys are an additional sign-in method. Users who register a passkey can still sign in with email/password unless you restrict that separately. + +### Can a user have multiple passkeys? + +Yes. Each device or security key can be registered separately (for example, laptop, phone, YubiKey). + +### What happens if a user skips optional setup? + +Kinde records the decline. They will not be prompted again until they clear that state (for example, by registering a passkey from the account portal, or if that decline is reset administratively). + +### Does passkey sign-in work for new user registration? + +No. The **Sign in with passkey** button is sign-in only. New users register with credentials (or SSO), then may be prompted to add a passkey. + +### Can I configure passkeys per application? + +Policy is set at the environment or organization level, not per application. All apps in an environment share the same passkey policy (subject to org overrides). + +### What plan do I need? + +All paid plans support passkeys (Pro, Plus, Scale, Enterprise). See [Kinde pricing](https://kinde.com/pricing/) for more information. \ No newline at end of file diff --git a/src/content/docs/authenticate/authentication-methods/sms-deliverability.mdx b/src/content/docs/authenticate/authentication-methods/sms-deliverability.mdx index dfabef657..ea46e8974 100644 --- a/src/content/docs/authenticate/authentication-methods/sms-deliverability.mdx +++ b/src/content/docs/authenticate/authentication-methods/sms-deliverability.mdx @@ -2,7 +2,7 @@ page_id: f18a5a74-23b3-43d8-8db9-440ee485e4d4 title: SMS deliverability in Kinde sidebar: - order: 9 + order: 10 relatedArticles: - 8b9376c4-308c-4eaa-a990-606fb8bbf770 - c2a21e18-b542-4c07-a3b3-206ed4ce9508