Sign users in
Pick the sign-in method from the table, then follow its section. Examples use the password facade prefix /auth, including Identity bearer and email-code routes that a host composes on that prefix. External sign-in is under /auth/external. To pick a call, see Choose your sign-in setup.
Compare the sign-in methods
| Method | Endpoints | Result | CSRF | Two-factor |
|---|---|---|---|---|
| Password, cookie (password facade default) | POST /auth/login | Application cookie, empty 200 body | No | 401 with title RequiresTwoFactor, or send the code in the first request |
| Password, Identity bearer | POST /auth/login, POST /auth/refresh | AccessTokenResponse JSON | No | 401 with title RequiresTwoFactor |
| Password, JWT | POST /auth/create, POST /auth/refresh | { accessToken, tokenType } and an HttpOnly refresh cookie | create: no. refresh: yes. | 401 with the extension requiresTwoFactor: true |
| Passkey | POST /auth/passkeys/requestOptions, POST /auth/passkeys/login | The password facade session. A cookie session sets the application cookie. | Yes | Skipped |
| GitHub or Google | GET /auth/external/login/{provider}, then the callback | Persistent application cookie, or a JWT refresh cookie | No | Skipped |
| Emailed code | POST /auth/emailCode/send, POST /auth/emailCode/verify | Identity bearer token JSON, an application cookie, or a JWT | No | 401 with title RequiresTwoFactor when the user has 2FA on |
Every login request uses the AuthEndpoints.Login rate limit. JWT POST /auth/refresh uses it too. Identity bearer POST /auth/refresh has no rate limit. See Rate-limit policies.
Sign in with a password and a cookie
MapPasswordAuth maps POST /auth/login. The body is Identity's LoginRequest: { "email", "password", "twoFactorCode"?, "twoFactorRecoveryCode"? }. Registration sets the user name to the email, so the email matches. The password check and the session write are in Password login.
- Send the credentials with
credentials: 'include'. Login does not need a CSRF token.const response = await fetch('/auth/login', { method: 'POST', credentials: 'include', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email, password }) }); - The cookie is a session cookie. Add
?useSessionCookies=falseto keep it after the browser closes. This route ignoresuseCookies. The same flag table is in Cookie sign-in. - Check the response:
200with an empty body and aSet-Cookieheader for.AspNetCore.Identity.Application: the user is signed in.401with titleRequiresTwoFactor: ask for a code. See Enter a two-factor code or a recovery code.401with titleUnauthorizedand detailInvalid credentials.: the password is wrong, the account is locked out, or the email is not confirmed. AuthEndpoints returns one response for all three so that it does not reveal which one applies.429: the rate limit rejected the request.
Sign in with a password and Identity bearer tokens
Use this method for native and mobile clients, and for browsers that keep the token in localStorage or sessionStorage. The password facade does not map it. Compose AddBearerAuthEndpoints and MapBearerAuthEndpoints. These steps use /auth. A host that also maps a cookie session puts the bearer routes on a second prefix, such as /bearer, because both sessions map POST /logout.
- Send the same
LoginRequestbody toPOST /auth/loginwithout query flags. - On success, read
{ "tokenType", "accessToken", "expiresIn", "refreshToken" }from the200body. Send the access token asAuthorization: Bearer <accessToken>. - To get a new access token, send
{ "refreshToken" }toPOST /auth/refresh.
useCookies=true on this login sets a persistent application cookie instead of returning tokens. useSessionCookies=true sets a session cookie. The 2FA challenge is the same as cookie login: 401 with title RequiresTwoFactor.
MapBearerAuthEndpoints maps no /csrfToken route. Identity bearer omits the CSRF token on the anonymous passkey ceremonies. The Identity ceremony state lives in the TwoFactorUserIdScheme cookie (Identity.TwoFactorUserId). That cookie is single-use state, not a credential, and clients must send it between the options call and the verify call. See Bearer auth.Sign in with a password and a JWT
On the password facade, set Session to AuthEndpointsSession.Jwt and pass Jwt. Or compose AddJwtEndpoints and MapJwtAuthEndpoints. Call modelBuilder.UseRefreshToken() on your DbContext and add a migration. See JWT module.
- Send
{ "email", "password", "twoFactorCode"?, "twoFactorRecoveryCode"? }toPOST /auth/createwithcredentials: 'include'. Theemailfield also accepts a user name.const { accessToken } = await fetch('/auth/create', { method: 'POST', credentials: 'include', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email, password }) }).then(r => r.json()); - On success, the
200body is{ "accessToken", "tokenType": "Bearer" }. The response also sets theAuthEndpoints.Jwt.RefreshTokencookie. That cookie is HttpOnly andSameSite=Strict. The refresh family ends 14 days after sign-in. Refreshing does not extend that cap. - To get a new access token, call
POST /auth/refreshwith the cookie and a CSRF token fromGET /auth/csrfToken. The body is{ "accessToken" }, with notokenType. Send one refresh at a time. A second use of the same refresh token revokes the whole family.
create returns these errors:
400 { "error": "invalid_request", ... }whenemailorpasswordis missing. This body is not problem details.401with detailInvalid credentials.for a wrong password, a lockout, or an unconfirmed email.401with the extensionrequiresTwoFactor: truewhen 2FA is on and the request has no code.
refresh returns 400 { "errors": [...] } when the cookie is missing, expired, revoked, or reused. Reuse revokes the family. Native clients can set JwtSessionOptions.RefreshTokenTransport to Body so login and refresh return refreshToken and skip antiforgery. See JWT module.
Enter a two-factor code or a recovery code
These steps apply to all three password methods. To turn 2FA on, see Turn on two-factor authentication.
- Send the email and password.
- If the response is the 2FA challenge, ask the user for a 6-digit authenticator code or a recovery code. Cookie and Identity bearer login return title
RequiresTwoFactor. JWTcreatereturns the extensionrequiresTwoFactor: true. - Send the same request again with
twoFactorCodeortwoFactorRecoveryCodeadded.
If the client already has the code, send it in the first request. A valid code succeeds in one round trip.
A wrong authenticator code or recovery code returns 401 with detail Invalid credentials. on cookie login, Identity bearer login, and JWT create. Each wrong code counts toward lockout.
Remembered browsers
A persistent cookie login (?useSessionCookies=false) with a valid twoFactorCode sets the Identity two-factor remember-client cookie. Later password logins from that browser skip the 2FA challenge. These logins do not set the cookie:
- A session cookie login (the default).
- A login with
twoFactorRecoveryCode. Each recovery code works once. - JWT
POST /auth/create.
To clear the cookie, send POST /auth/manage/2fa with { "forgetMachine": true }, or call POST /auth/logout.
Sign in with a passkey
On the password facade, set Passkeys.ServerDomain. That maps these routes under /auth/passkeys, and it also maps POST /passkeys/register. Login without that register route is in Passkeys. To finish in JWT, set Session to Jwt on the password facade, or pass AuthEndpointsSession.Jwt to MapPasskeySignInEndpoints. See Sign-in completers.
Send credentials: 'include' on both requests. A cookie session and JWT cookie refresh also send the CSRF header. Identity bearer and JWT body refresh do not. The Identity ceremony state lives in the TwoFactorUserIdScheme cookie (Identity.TwoFactorUserId). That cookie is single-use state, not a credential, and the client must send it between the options call and the verify call.
- Get request options from
POST /auth/passkeys/requestOptions. Send{}for a discoverable credential, or{ "email" }to sign in identifier-first. An email lets the response reveal throughallowCredentialsthat the account has passkeys. - Call
navigator.credentials.get. If the user cancels, stop. - Send the credential to
POST /auth/passkeys/loginwith{ "credentialJson" }. A cookie session sets the application cookie. Add?useSessionCookies=falsefor a persistent cookie.useCookiesis ignored on that session. A map that does not pass a session uses the Identity bearer completer unless a query flag selects a cookie. See Responses and errors.const headers = { 'Content-Type': 'application/json', 'RequestVerificationToken': csrfToken }; const options = await fetch('/auth/passkeys/requestOptions', { method: 'POST', credentials: 'include', headers, body: '{}' }).then(r => r.json()); const credential = await navigator.credentials.get({ publicKey: PublicKeyCredential.parseRequestOptionsFromJSON(options) }); const response = await fetch('/auth/passkeys/login', { method: 'POST', credentials: 'include', headers, body: JSON.stringify({ credentialJson: JSON.stringify(credential) }) }); - Check the response:
200with an empty body and a cookie: the user is signed in.200with{ "accessToken", "tokenType" }and a refresh cookie: the JWT completer signed the user in.401with detailInvalid credentials.: the account is locked out or the email is not confirmed.400with titleInvalid Credential: the assertion failed orcredentialJsonwas empty.400validation problemInvalidPasskeyState: no ceremony was underway. Start again from step 1.
Sign in with GitHub or Google
Set up the packages and routes as in Register with GitHub or Google. The same callback signs users in.
- Send the browser to the login route with a top-level navigation:
window.location.assign('/auth/external/login/google?returnUrl=' + encodeURIComponent('/dashboard')); - The callback signs in a user who already has this provider login. It refuses a local user with the same email and no link, with the error
auto_link_disabled. WithAutoLinkByEmailset totrue, it links that user only when the provider email is verified and the local email is confirmed. - On success, the default session is a
302toreturnUrlwith the application cookie. The cookie is persistent becauseIsPersistentdefaults totrue. PassAuthEndpointsSession.Jwtto set the JWT refresh cookie, then callPOST /auth/refreshwith a CSRF token. Body transport throws at map time. PassAuthEndpointsSession.IdentityBearerto write the token body instead of redirecting. See Sign-in completers.
returnUrl must be a rooted local path, or an absolute URL whose origin is in AllowedReturnUrlOrigins. Any other value falls back to DefaultReturnUrl.
Sign in with an emailed code
Call AddEmailCodeEndpoints and map MapEmailCodeEndpoints. The password facade does not map these routes. Add them on its prefix as in Add email code to the password facade. The steps, the magic link, and sign-up are in Sign in with an emailed code.
POST /auth/emailCode/send and POST /auth/emailCode/verify do not use a CSRF token. Verify uses the AuthEndpoints.Login rate limit. When the user has two-factor authentication on and RequireTwoFactor is true (the default), verify returns 401 with title RequiresTwoFactor until the body includes twoFactorCode or twoFactorRecoveryCode.
Help a user who cannot sign in
- Forgotten password.
POST /auth/forgotPasswordalways returns200. AuthEndpoints sends mail only to a confirmed account. See Reset a forgotten password. - Lost authenticator. The user signs in with a recovery code instead of a TOTP code.
- Locked out. Lockout uses Identity's defaults. Change them with
ConfigureIdentity. See Configuration options. - Unconfirmed email. The user opens the confirmation link first. See Register users.
What sign-in does not support
AuthEndpoints does not include these features:
- Two-factor codes by SMS. Identity has an email token provider, but no endpoint exposes it as a second factor. An emailed one-time code is a first factor. See Sign in with an emailed code.
- A passkey as a second factor after a password. Passkeys are a first factor only.
- Built-in Apple or Microsoft providers.
- An endpoint that lists or revokes a user's other sessions.
- An admin endpoint that unlocks an account.