Serverpod Auth
Developmentserverpod-authServerpod Auth is an Agent Skill for development published in the serverpod/serverpod repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Serverpod Authentication — Signing in users, verify if they are authenticated, assinging scopes (e.g., admin). Use when adding features that require the user to be signed in.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/serverpod/serverpod/blob/HEAD/packages/serverpod/skills/serverpod-auth/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/serverpod-auth, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Serverpod Authentication
Serverpod has authentication built in. Pre-configured with email. Most social sign-ins supported (Apple, Google, GitHub, Facebook, Microsoft, etc) but need configuration.
Flutter app
Use SignInWidget. It provides its own Material surface, so it also renders
correctly when mixed with non-Material design systems. Simplified example:
import 'package:serverpod_auth_idp_flutter/serverpod_auth_idp_flutter.dart';
class _SignInScreenState extends State<SignInScreen> {
bool _isSignedIn = false;
@override
void initState() {
super.initState();
client.auth.authInfoListenable.addListener(_updateSignedInState);
_isSignedIn = client.auth.isAuthenticated;
}
@override
void dispose() {
client.auth.authInfoListenable.removeListener(_updateSignedInState);
super.dispose();
}
void _updateSignedInState() {
setState(() {
_isSignedIn = client.auth.isAuthenticated;
});
}
@override
Widget build(BuildContext context) {
return _isSignedIn
? widget.child
: Center(
child: SignInWidget(
client: client,
onAuthenticated: () {
_showSnackBar(message: 'User authenticated.');
},
onError: (error) {
_showSnackBar(message: 'Authentication failed: $error');
},
),
);
}
}
Check signed-in state: _isSignedIn = client.auth.isAuthenticated;
Sign out: client.auth.signOutAllDevices() or client.auth.signOutDevice()
Get user profile (email, full name, etc): final userProfile = await client.modules.serverpod_auth_core.userProfileInfo.get()
Server-side
Require the user to be signed in or have a specific scope
class MyEndpoint extends Endpoint {
// Require the user to be signed in to access methods in this endpoint.
@override
bool get requireLogin => true;
// Require the user to have the admin scope.
@override
Set<Scope> get requiredScopes => {Scope.admin};
// This method can only be accessed if the user is admin.
Future<void> myMethod(Session session) async {
...
}
...
}
User id and info
import 'package:serverpod_auth_idp_server/serverpod_auth_idp_server.dart';
// Get authenticated user's ID.
final userIdUuidValue = session.authenticated?.authUserId;
// Get the user profile (full name, email, etc)
var userProfile = await session.authenticated?.userProfile(session);
// Find a user profile by email.
final profiles = await AuthServices.instance.userProfiles.admin
.listUserProfiles(
session,
email: email.toLowerCase(),
limit: 1,
);
final userProfile = profiles.firstOrNull;
// Get authentication info for user id (for editing scopes, etc).
final authUsers = AuthServices.instance.authUsers;
final authUser = await authUsers.get(
session,
authUserId: userProfile.authUserId,
);
Attaching additional info to a user
Create a model:
class: MyDomainData
table: my_domain_data
fields:
### The [AuthUser] this profile belongs to
authUser: module:serverpod_auth_core:AuthUser?, relation(onDelete=Cascade)
additionalInfo: String
indexes:
auth_user_id_unique_idx:
fields: authUserId
unique: true
Find the info:
final authUserId = session.authenticated?.authUserId;
final additionalInfo = await MyDomainData.db.findFirstRow(
session,
where: (t) => t.authUserId.equals(authUserId!),
);
Managing scopes
import 'package:serverpod_auth_idp_server/core.dart';
// Update a user's scope.
await AuthServices.instance.authUsers.update(
session,
authUserId: authUserId,
scopes: {Scope.admin},
);
// Use custom scope.
class CustomScope extends Scope {
const CustomScope(String name) : super(name);
static const userRead = CustomScope('userRead');
static const userWrite = CustomScope('userWrite');
}
Enable editing user profile (from the client)
import 'package:serverpod/serverpod.dart';
import 'package:serverpod_auth_idp_server/core.dart';
class UserProfileEditEndpoint extends UserProfileEditBaseEndpoint {}
Social sign-ins
Requires set up by the user to configure (e.g., GCP console or Apple developer portal). Use official docs as reference. Supported: