From a08945903059a7a66e2299e805c987e5024d0a4d Mon Sep 17 00:00:00 2001 From: Ebenezer Don Date: Wed, 11 Dec 2024 13:19:58 +0000 Subject: [PATCH 1/2] docs: add user verification journey to auth docs - Add new verification journey page - Add verification to auth journeys navigation --- src/routes/docs/products/auth/+layout.svelte | 4 + .../products/auth/verification/+page.markdoc | 93 +++++++++++++++++++ 2 files changed, 97 insertions(+) create mode 100644 src/routes/docs/products/auth/verification/+page.markdoc diff --git a/src/routes/docs/products/auth/+layout.svelte b/src/routes/docs/products/auth/+layout.svelte index 0b202b0f1c..48192bbca5 100644 --- a/src/routes/docs/products/auth/+layout.svelte +++ b/src/routes/docs/products/auth/+layout.svelte @@ -92,6 +92,10 @@ { label: 'Multi-factor authentication', href: '/docs/products/auth/mfa' + }, + { + label: 'User verification', + href: '/docs/products/auth/verification' } ] }, diff --git a/src/routes/docs/products/auth/verification/+page.markdoc b/src/routes/docs/products/auth/verification/+page.markdoc new file mode 100644 index 0000000000..8781a917b5 --- /dev/null +++ b/src/routes/docs/products/auth/verification/+page.markdoc @@ -0,0 +1,93 @@ +--- +layout: article +title: User verification +description: Learn about Appwrite's email and phone verification system, including verification flows and role-based access control. +--- + +User verification in Appwrite allows you to verify user email addresses and phone numbers. Users don't need to be verified to log in, but you can restrict resource access to verified users only using permissions. + +# Email verification {% #email-verification %} + +To verify a user's email, first send a verification email with a redirect URL. The verification secrets will be appended as query parameters to the redirect URL: + +```client-web +import { Client, Account } from "appwrite"; + +const client = new Client() + .setProject('') // Your project ID + +const account = new Account(client); + +const promise = account.createVerification('https://example.com/verify'); + +promise.then(function (response) { + console.log(response); // Success +}, function (error) { + console.log(error); // Failure +}); +``` + +After the user clicks the link in the email, they will be redirected to your site with the query parameters `userId` and `secret`. If you're on a mobile platform, you will need to create the appropriate deep link to handle the verification. + +Next, implement the verification page that handles the redirect: + +```client-web +import { Client, Account } from "appwrite"; + +const client = new Client() + .setProject(''); // Your project ID + +const account = new Account(client); + +const urlParams = new URLSearchParams(window.location.search); +const secret = urlParams.get('secret'); +const userId = urlParams.get('userId'); + +const promise = account.updateVerification(userId, secret); + +promise.then(function (response) { + console.log(response); // Success +}, function (error) { + console.log(error); // Failure +}); +``` + +# Phone verification {% #phone-verification %} + +To verify a phone number, first ensure the user has a phone number set on their account: + +```client-web +const response = await account.updatePhone( + '+12065550100', // phone + 'password' // password +); +``` + +Then initiate verification by calling `createPhoneVerification`: + +```client-web +const response = await account.createPhoneVerification(); +``` + +After the user receives the verification code, complete verification by calling `updatePhoneVerification`: + +```client-web +const response = await account.updatePhoneVerification( + '[USER_ID]', // userId + '[SECRET]' // secret +); +``` + +# Role-based access {% #role-based-access %} + +You can restrict resource access to verified users only using permissions through the `user([USER_ID], "verified")` role. This role is automatically assigned after successful verification. + +# Verification events {% #verification-events %} + +The following events are triggered during the verification process: + +- `users.*.verification.*` - Triggers on any user's verification token event +- `users.*.verification.*.create` - Triggers when a verification token for a user is created +- `users.*.verification.*.update` - Triggers when a verification token for a user is validated + +Each event returns a Token Object. \ No newline at end of file From b2accb4823b0c5befb452f6c8b9c7465027ea083 Mon Sep 17 00:00:00 2001 From: Ebenezer Don Date: Fri, 13 Dec 2024 11:18:19 +0000 Subject: [PATCH 2/2] Add code examples for clients other than web --- .../products/auth/verification/+page.markdoc | 191 +++++++++++++++++- 1 file changed, 190 insertions(+), 1 deletion(-) diff --git a/src/routes/docs/products/auth/verification/+page.markdoc b/src/routes/docs/products/auth/verification/+page.markdoc index 8781a917b5..13e51a57e9 100644 --- a/src/routes/docs/products/auth/verification/+page.markdoc +++ b/src/routes/docs/products/auth/verification/+page.markdoc @@ -10,10 +10,12 @@ User verification in Appwrite allows you to verify user email addresses and phon To verify a user's email, first send a verification email with a redirect URL. The verification secrets will be appended as query parameters to the redirect URL: +{% multicode %} ```client-web import { Client, Account } from "appwrite"; const client = new Client() + .setEndpoint('https://cloud.appwrite.io/v1') .setProject('') // Your project ID const account = new Account(client); @@ -27,15 +29,69 @@ promise.then(function (response) { }); ``` +```client-flutter +import 'package:appwrite/appwrite.dart'; + +void main() { + Client client = Client() + .setEndpoint('https://cloud.appwrite.io/v1') + .setProject(''); + + Account account = Account(client); + + Future result = account.createVerification( + url: 'https://example.com/verify' + ); + + result.then((response) { + print(response); + }).catchError((error) { + print(error.response); + }); +} +``` + +```client-apple +import Appwrite + +let client = Client() + .setEndpoint("https://cloud.appwrite.io/v1") + .setProject("") + +let account = Account(client) + +let token = try await account.createVerification( + url: "https://example.com/verify" +) +``` + +```client-android-kotlin +import io.appwrite.Client +import io.appwrite.services.Account + +val client = Client(context) + .setEndpoint("https://cloud.appwrite.io/v1") + .setProject("") + +val account = Account(client) + +val response = account.createVerification( + url = "https://example.com/verify" +) +``` +{% /multicode %} + After the user clicks the link in the email, they will be redirected to your site with the query parameters `userId` and `secret`. If you're on a mobile platform, you will need to create the appropriate deep link to handle the verification. Next, implement the verification page that handles the redirect: +{% multicode %} ```client-web import { Client, Account } from "appwrite"; const client = new Client() - .setProject(''); // Your project ID + .setEndpoint('https://cloud.appwrite.io/v1') + .setProject(''); const account = new Account(client); @@ -52,10 +108,66 @@ promise.then(function (response) { }); ``` +```client-flutter +import 'package:appwrite/appwrite.dart'; + +void main() { + Client client = Client() + .setEndpoint('https://cloud.appwrite.io/v1') + .setProject(''); + + Account account = Account(client); + + Future result = account.updateVerification( + userId: '', + secret: '' + ); + + result.then((response) { + print(response); + }).catchError((error) { + print(error.response); + }); +} +``` + +```client-apple +import Appwrite + +let client = Client() + .setEndpoint("https://cloud.appwrite.io/v1") + .setProject("") + +let account = Account(client) + +let response = try await account.updateVerification( + userId: "", + secret: "" +) +``` + +```client-android-kotlin +import io.appwrite.Client +import io.appwrite.services.Account + +val client = Client(context) + .setEndpoint("https://cloud.appwrite.io/v1") + .setProject("") + +val account = Account(client) + +val response = account.updateVerification( + userId = "", + secret = "" +) +``` +{% /multicode %} + # Phone verification {% #phone-verification %} To verify a phone number, first ensure the user has a phone number set on their account: +{% multicode %} ```client-web const response = await account.updatePhone( '+12065550100', // phone @@ -63,14 +175,63 @@ const response = await account.updatePhone( ); ``` +```client-flutter +Future result = account.updatePhone( + phone: '+12065550100', + password: 'password' +); + +result.then((response) { + print(response); +}).catchError((error) { + print(error.response); +}); +``` + +```client-apple +let response = try await account.updatePhone( + phone: "+12065550100", + password: "password" +) +``` + +```client-android-kotlin +val response = account.updatePhone( + phone = "+12065550100", + password = "password" +) +``` +{% /multicode %} + Then initiate verification by calling `createPhoneVerification`: +{% multicode %} ```client-web const response = await account.createPhoneVerification(); ``` +```client-flutter +Future result = account.createPhoneVerification(); + +result.then((response) { + print(response); +}).catchError((error) { + print(error.response); +}); +``` + +```client-apple +let response = try await account.createPhoneVerification() +``` + +```client-android-kotlin +val response = account.createPhoneVerification() +``` +{% /multicode %} + After the user receives the verification code, complete verification by calling `updatePhoneVerification`: +{% multicode %} ```client-web const response = await account.updatePhoneVerification( '[USER_ID]', // userId @@ -78,6 +239,34 @@ const response = await account.updatePhoneVerification( ); ``` +```client-flutter +Future result = account.updatePhoneVerification( + userId: '[USER_ID]', + secret: '[SECRET]' +); + +result.then((response) { + print(response); +}).catchError((error) { + print(error.response); +}); +``` + +```client-apple +let response = try await account.updatePhoneVerification( + userId: "[USER_ID]", + secret: "[SECRET]" +) +``` + +```client-android-kotlin +val response = account.updatePhoneVerification( + userId = "[USER_ID]", + secret = "[SECRET]" +) +``` +{% /multicode %} + # Role-based access {% #role-based-access %} You can restrict resource access to verified users only using permissions through the `user([USER_ID], "verified")` role. This role is automatically assigned after successful verification.