From 630192ec06ae53a8c9e1a61f774303f767a8f794 Mon Sep 17 00:00:00 2001 From: Marcelo Soares Date: Wed, 4 Feb 2026 15:57:49 -0300 Subject: [PATCH 1/2] docs: Add docs on how to react to user creation --- .../03-working-with-users.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/06-concepts/11-authentication/03-working-with-users.md b/docs/06-concepts/11-authentication/03-working-with-users.md index 42db3c91..7f3e935a 100644 --- a/docs/06-concepts/11-authentication/03-working-with-users.md +++ b/docs/06-concepts/11-authentication/03-working-with-users.md @@ -48,6 +48,45 @@ await AuthServices.instance.authUsers.create( When a user is blocked, they will not be able to sign in until they are unblocked. However, blocking a user does not automatically revoke their existing sessions. Be sure to revoke existing sessions for a complete block operation. See [Revoking tokens](./token-managers/managing-tokens#revoking-tokens) for more details. ::: +## User creation callbacks + +You can react when an auth user is created and control their initial scopes and blocked status by using the `AuthUsersConfig` callbacks. Configure them when initializing auth services on the `pod` object. + +:::warning +Both callbacks receive a `transaction` parameter that should be used on all operations performed inside the callback. Failing to pass the transaction to database operations might lead to entries not being found or changes not being rolled back together. +::: + +### Reacting to the user created event + +Use the `onAfterAuthUserCreated` callback to run logic after a new auth user has been created (for example, to create related domain data or send a welcome notification). The callback receives the current session, the newly created auth user, and the ongoing transaction. + +```dart +pod.initializeAuthServices( + ... + authUsersConfig: AuthUsersConfig( + onAfterAuthUserCreated: (session, authUser, {required transaction}) { + // Do something with the new auth user (e.g. create related data) + }, + ), +); +``` + +### Setting default scopes and blocked status + +Use the `onBeforeAuthUserCreated` callback to set default scopes or blocked status for new auth users. The callback receives the session, the scopes and blocked value that would be used by default, and the transaction. Return a record with the `scopes` and `blocked` values you want to apply; you can add or remove scopes or force the user to be blocked. + +```dart +pod.initializeAuthServices( + ... + authUsersConfig: AuthUsersConfig( + onBeforeAuthUserCreated: (session, scopes, blocked, {required transaction}) { + // Set default scopes (e.g. add Scope.admin) and optionally block the user + return (scopes: {...scopes, Scope.admin}, blocked: blocked); + }, + ), +); +``` + ## User profiles By default, all authenticated users have a `UserProfile` object that contains information about the signed-in user. To access the `UserProfile` object, you can use the `userProfile` extension on the `AuthenticationInfo` object. From 322d43b8c15cfae452dbe59cdc680be04bea6f3d Mon Sep 17 00:00:00 2001 From: Marcelo Soares Date: Wed, 4 Feb 2026 15:59:10 -0300 Subject: [PATCH 2/2] chore: Replicate changes to versioned docs --- .../03-working-with-users.md | 39 +++++++++++++++++++ .../03-working-with-users.md | 39 +++++++++++++++++++ .../03-working-with-users.md | 39 +++++++++++++++++++ 3 files changed, 117 insertions(+) diff --git a/versioned_docs/version-3.0.0/06-concepts/11-authentication/03-working-with-users.md b/versioned_docs/version-3.0.0/06-concepts/11-authentication/03-working-with-users.md index 42db3c91..7f3e935a 100644 --- a/versioned_docs/version-3.0.0/06-concepts/11-authentication/03-working-with-users.md +++ b/versioned_docs/version-3.0.0/06-concepts/11-authentication/03-working-with-users.md @@ -48,6 +48,45 @@ await AuthServices.instance.authUsers.create( When a user is blocked, they will not be able to sign in until they are unblocked. However, blocking a user does not automatically revoke their existing sessions. Be sure to revoke existing sessions for a complete block operation. See [Revoking tokens](./token-managers/managing-tokens#revoking-tokens) for more details. ::: +## User creation callbacks + +You can react when an auth user is created and control their initial scopes and blocked status by using the `AuthUsersConfig` callbacks. Configure them when initializing auth services on the `pod` object. + +:::warning +Both callbacks receive a `transaction` parameter that should be used on all operations performed inside the callback. Failing to pass the transaction to database operations might lead to entries not being found or changes not being rolled back together. +::: + +### Reacting to the user created event + +Use the `onAfterAuthUserCreated` callback to run logic after a new auth user has been created (for example, to create related domain data or send a welcome notification). The callback receives the current session, the newly created auth user, and the ongoing transaction. + +```dart +pod.initializeAuthServices( + ... + authUsersConfig: AuthUsersConfig( + onAfterAuthUserCreated: (session, authUser, {required transaction}) { + // Do something with the new auth user (e.g. create related data) + }, + ), +); +``` + +### Setting default scopes and blocked status + +Use the `onBeforeAuthUserCreated` callback to set default scopes or blocked status for new auth users. The callback receives the session, the scopes and blocked value that would be used by default, and the transaction. Return a record with the `scopes` and `blocked` values you want to apply; you can add or remove scopes or force the user to be blocked. + +```dart +pod.initializeAuthServices( + ... + authUsersConfig: AuthUsersConfig( + onBeforeAuthUserCreated: (session, scopes, blocked, {required transaction}) { + // Set default scopes (e.g. add Scope.admin) and optionally block the user + return (scopes: {...scopes, Scope.admin}, blocked: blocked); + }, + ), +); +``` + ## User profiles By default, all authenticated users have a `UserProfile` object that contains information about the signed-in user. To access the `UserProfile` object, you can use the `userProfile` extension on the `AuthenticationInfo` object. diff --git a/versioned_docs/version-3.1.0/06-concepts/11-authentication/03-working-with-users.md b/versioned_docs/version-3.1.0/06-concepts/11-authentication/03-working-with-users.md index 42db3c91..7f3e935a 100644 --- a/versioned_docs/version-3.1.0/06-concepts/11-authentication/03-working-with-users.md +++ b/versioned_docs/version-3.1.0/06-concepts/11-authentication/03-working-with-users.md @@ -48,6 +48,45 @@ await AuthServices.instance.authUsers.create( When a user is blocked, they will not be able to sign in until they are unblocked. However, blocking a user does not automatically revoke their existing sessions. Be sure to revoke existing sessions for a complete block operation. See [Revoking tokens](./token-managers/managing-tokens#revoking-tokens) for more details. ::: +## User creation callbacks + +You can react when an auth user is created and control their initial scopes and blocked status by using the `AuthUsersConfig` callbacks. Configure them when initializing auth services on the `pod` object. + +:::warning +Both callbacks receive a `transaction` parameter that should be used on all operations performed inside the callback. Failing to pass the transaction to database operations might lead to entries not being found or changes not being rolled back together. +::: + +### Reacting to the user created event + +Use the `onAfterAuthUserCreated` callback to run logic after a new auth user has been created (for example, to create related domain data or send a welcome notification). The callback receives the current session, the newly created auth user, and the ongoing transaction. + +```dart +pod.initializeAuthServices( + ... + authUsersConfig: AuthUsersConfig( + onAfterAuthUserCreated: (session, authUser, {required transaction}) { + // Do something with the new auth user (e.g. create related data) + }, + ), +); +``` + +### Setting default scopes and blocked status + +Use the `onBeforeAuthUserCreated` callback to set default scopes or blocked status for new auth users. The callback receives the session, the scopes and blocked value that would be used by default, and the transaction. Return a record with the `scopes` and `blocked` values you want to apply; you can add or remove scopes or force the user to be blocked. + +```dart +pod.initializeAuthServices( + ... + authUsersConfig: AuthUsersConfig( + onBeforeAuthUserCreated: (session, scopes, blocked, {required transaction}) { + // Set default scopes (e.g. add Scope.admin) and optionally block the user + return (scopes: {...scopes, Scope.admin}, blocked: blocked); + }, + ), +); +``` + ## User profiles By default, all authenticated users have a `UserProfile` object that contains information about the signed-in user. To access the `UserProfile` object, you can use the `userProfile` extension on the `AuthenticationInfo` object. diff --git a/versioned_docs/version-3.2.0/06-concepts/11-authentication/03-working-with-users.md b/versioned_docs/version-3.2.0/06-concepts/11-authentication/03-working-with-users.md index 42db3c91..7f3e935a 100644 --- a/versioned_docs/version-3.2.0/06-concepts/11-authentication/03-working-with-users.md +++ b/versioned_docs/version-3.2.0/06-concepts/11-authentication/03-working-with-users.md @@ -48,6 +48,45 @@ await AuthServices.instance.authUsers.create( When a user is blocked, they will not be able to sign in until they are unblocked. However, blocking a user does not automatically revoke their existing sessions. Be sure to revoke existing sessions for a complete block operation. See [Revoking tokens](./token-managers/managing-tokens#revoking-tokens) for more details. ::: +## User creation callbacks + +You can react when an auth user is created and control their initial scopes and blocked status by using the `AuthUsersConfig` callbacks. Configure them when initializing auth services on the `pod` object. + +:::warning +Both callbacks receive a `transaction` parameter that should be used on all operations performed inside the callback. Failing to pass the transaction to database operations might lead to entries not being found or changes not being rolled back together. +::: + +### Reacting to the user created event + +Use the `onAfterAuthUserCreated` callback to run logic after a new auth user has been created (for example, to create related domain data or send a welcome notification). The callback receives the current session, the newly created auth user, and the ongoing transaction. + +```dart +pod.initializeAuthServices( + ... + authUsersConfig: AuthUsersConfig( + onAfterAuthUserCreated: (session, authUser, {required transaction}) { + // Do something with the new auth user (e.g. create related data) + }, + ), +); +``` + +### Setting default scopes and blocked status + +Use the `onBeforeAuthUserCreated` callback to set default scopes or blocked status for new auth users. The callback receives the session, the scopes and blocked value that would be used by default, and the transaction. Return a record with the `scopes` and `blocked` values you want to apply; you can add or remove scopes or force the user to be blocked. + +```dart +pod.initializeAuthServices( + ... + authUsersConfig: AuthUsersConfig( + onBeforeAuthUserCreated: (session, scopes, blocked, {required transaction}) { + // Set default scopes (e.g. add Scope.admin) and optionally block the user + return (scopes: {...scopes, Scope.admin}, blocked: blocked); + }, + ), +); +``` + ## User profiles By default, all authenticated users have a `UserProfile` object that contains information about the signed-in user. To access the `UserProfile` object, you can use the `userProfile` extension on the `AuthenticationInfo` object.