Auth service provides access to the current user’s identity. Unlike vanilla Convex (which returns UserIdentity | null), the Confect Auth service returns an Effect that fails with a typed error when no user is authenticated.
Getting the user identity
getUserIdentity succeeds with the user’s UserIdentity or fails with NoUserIdentityFoundError.
To require an authenticated user across a whole group of functions—and provide the loaded user to every handler—use middleware instead of repeating the lookup in each handler.
For authorization policies that differ only by allowed roles or a resource argument name, declare middleware options rather than creating a separate middleware for every variation. One role gate can accept { admin: true } on one function and { editor: true, admin: true } on another. If you repeat a guard on the same function, every attachment must pass.
Handling unauthenticated requests
UseEffect.catchTag to handle the case where no user is logged in.
Configuration
Auth provider configuration goes inconfect/auth.ts, which is passed through to Convex as-is. See the Convex auth documentation for setup details.
Signing deployment JWTs
Confect exposes Convex’sctx.auth.signJwt() through the separate MutationAuth service in confect/_generated/services; Auth remains identity-only. MutationAuth.signJwt(options) returns a lazy Effect<string> instead of a Promise. Native rejections become defects rather than typed errors.
Confect checks the signing capability at compile time: only mutation handlers and middleware implementations restricted to mutations can require MutationAuth.