Skip to content

docs: Add docs on how to react to user creation #409

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marcelomendoncasoares merged 2 commits into from
Feb 5, 2026
+156 −0
Merged

docs: Add docs on how to react to user creation #409

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
630192e
docs: Add docs on how to react to user creation
marcelomendoncasoares Feb 4, 2026
322d43b
chore: Replicate changes to versioned docs
marcelomendoncasoares Feb 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions docs/06-concepts/11-authentication/03-working-with-users.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
39 changes: 39 additions & 0 deletions ...ioned_docs/version-3.0.0/06-concepts/11-authentication/03-working-with-users.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
39 changes: 39 additions & 0 deletions ...ioned_docs/version-3.1.0/06-concepts/11-authentication/03-working-with-users.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
39 changes: 39 additions & 0 deletions ...ioned_docs/version-3.2.0/06-concepts/11-authentication/03-working-with-users.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down