Authentication

This page walks through the three entry points to a session — register, login, logout — end to end: which config flags turn each path on, exactly what each endpoint takes and returns, every error it can produce, and three ways to call it: curl, directly in Go via Auth.Services, and from a browser client.

For the full path/param reference across every route (not just these three), see Routes. For the error envelope shape and codes shared across the whole API, see Error Handling.

Configuration

Three flags on RegistrationConfig decide which of the flows below are reachable. Login itself is never gated by any of them — they only govern how an account gets created, not whether an existing one can sign in.

goauth.WithRegistration(goauth.RegistrationConfig{
    EnableEmailPassword:      true,               // optional, default true — turns on POST /auth/register
    EnableOAuth:              true,               // optional, default true — see the Callout below
    EnableInvite:             false,              // optional, default false — turns on the invite endpoints; requires a mailer
    AllowPublic:              true,               // optional, default true — false makes email/password registration invite-only (403 forbidden)
    RequireEmailVerification: false,              // optional, default false — register/login return requiresVerification instead of a session
    InviteTTL:                7 * 24 * time.Hour, // optional, default 7d
    VerificationCodeTTL:      15 * time.Minute,   // optional, default 15m
})

Full field reference, defaults, and validation errors live on Configuration — this page only recaps the fields that change how register/login/logout behave.

Frontend client setup

The Client examples below call a small apiRequest(baseUrl, method, path, body) helper — cookies-included fetch plus CSRF header handling. It's defined once on the Client → Setup page rather than repeated in every section here; see that page for what it does and why. A named-method wrapper built on top of it (authApi.login(...), etc.) lives on Client → Authentication.

Origin checking

Every state-changing route (POST/PUT/PATCH/DELETE) runs through middleware.OriginCheck before it reaches a handler. By default (AllowMissingCSRFHeaders: false), a request with neither an Origin nor a Referer header gets a flat 403 Forbidden - CSRF headers missing — which is why every curl example on this page below sets -H "Origin: https://myapp.com". Without it, they 403 against any real deployment.

Register

Three ways to create an account, gated by the flags above:

• Email/password (EnableEmailPassword) — immediate session, or a verification step first if RequireEmailVerification is on.
• Invite (EnableInvite) — the account is created pre-verified; there's no separate verification step.
• OAuth — covered on the Providers pages, not here, since the flow is a browser redirect rather than a JSON request/response.

Register with email/password — POST /auth/register

Requires EnableEmailPassword: true and AllowPublic: true.

Request body

Response — RequireEmailVerification: false (201 Created) — a session is issued immediately:

{
  "user": {
    "id": "b3f1...",
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "role": "user",
    "isVerified": false,
    "isBanned": false,
    "orgOwnerCount": 0,
    "createdAt": "2026-08-09T12:00:00Z",
    "updatedAt": "2026-08-09T12:00:00Z"
  },
  "session": {
    "id": "9e2c...",
    "userId": "b3f1...",
    "ipAddress": "203.0.113.4",
    "userAgent": "Mozilla/5.0 ...",
    "isRevoked": false,
    "expiresAt": "2026-09-08T12:00:00Z",
    "refreshExpiresAt": "2026-09-08T12:00:00Z",
    "createdAt": "2026-08-09T12:00:00Z"
  }
}

The raw session and refresh tokens are never in this body — they're set as HttpOnly cookies (goauth_session, goauth_refresh by default) on the same response, and the CSRF cookie is rotated at the same time. isVerified is false here even though no verification was required — that flag only ever flips to true through the verification flow itself.

Response — RequireEmailVerification: true (201 Created) — no session yet:

{
  "user": { "...": "same shape as above, isVerified: false" },
  "requiresVerification": true,
  "message": "Verification email sent. Please verify your email to continue."
}

No cookies are set on this response. The account exists in the database, but there's nothing to authenticate with yet — the client has to go through Verifying the email below.

Response — TwoFactorConfig.RequireEmail2FA: true (201 Created) — a session is not issued; register gates on this flag alone, independent of RequireEmailVerification, so the two never stack (see Two-factor authentication):

{
  "user": { "...": "same shape as above" },
  "requiresTwoFactor": true,
  "codeSent": true,
  "challengeId": "c4a1...",
  "expiresAt": "2026-08-09T12:05:00Z",
  "message": "Two-factor code sent to your email"
}

Alongside this body, a binding cookie is set (_2fa_challenge by default) — see Two-factor authentication for what it's for and how POST /auth/2fa/verify uses it.

Errors

curl

curl -X POST https://api.myapp.com/auth/register \
  -H "Content-Type: application/json" \
  -H "Origin: https://myapp.com" \
  -c cookies.txt \
  -d '{"email":"ada@example.com","password":"correct horse battery staple 1","name":"Ada Lovelace"}'

-c cookies.txt saves the Set-Cookie headers so later requests (curl's -b cookies.txt) reuse the session — curl doesn't do this automatically the way a browser does. The Origin header is required too — see Origin checking above.

Programmatic (Go)

Calling the service directly skips HTTP entirely — no cookies get set for you, so you own the raw tokens from here.

result, err := auth.Services.Auth.Register(ctx, goauth.RegisterInput{
    Email:     "ada@example.com",
    Password:  "correct horse battery staple 1",
    Name:      "Ada Lovelace",
    IP:        r.RemoteAddr,  // optional — only used for the audit event and session device metadata
    UserAgent: r.UserAgent(), // optional — same
})
if err != nil {
    // err is always a *domain.AuthError under the hood — extract it with
    // errors.As(err, &authErr) for authErr.Code/.Message, or match a
    // specific one with errors.Is(err, domain.ErrEmailAlreadyExists)
    // — see Error Handling → Handling errors programmatically.
}

if result.RequiresVerification {
    // result.Session, result.SessionToken, result.RefreshToken are all zero-valued here
} else if result.RequiresTwoFactor {
    // no session issued yet — result.TwoFactorChallenge is the challenge id,
    // result.BindingToken() is what the handler would set as a cookie —
    // same shape as the Login gated response below
} else {
    // result.SessionToken / result.RefreshToken are the raw values —
    // set them as cookies yourself, or hand them to your own token transport
}

Client

const result = await apiRequest(API_BASE, "POST", "/auth/register", {
  email: "ada@example.com",
  password: "correct horse battery staple 1",
  name: "Ada Lovelace",
});

if (result.requiresVerification) {
  // show "check your email" — no session exists yet
} else {
  setUser(result.user); // cookies are already set by the browser
}

For a complete register form with error handling, see Client → Register.

Verifying the email

Only relevant when RequireEmailVerification: true. Two ways in: a link with a code (POST /auth/verify-email), or a resend if the email never arrived.

POST /auth/verify-email — body { "code": "..." }. On success, the handler verifies the user and immediately creates a session in the same request — this is the only place verification and login happen in one step.

{
  "user": { "...": "isVerified is now true" },
  "session": { "...": "same shape as register" }
}

POST /auth/verify-email/resend — body { "email": "..." }. Always returns a generic success message whether or not the account exists, to avoid leaking which emails are registered.

curl

curl -X POST https://api.myapp.com/auth/verify-email \
  -H "Content-Type: application/json" \
  -H "Origin: https://myapp.com" \
  -c cookies.txt \
  -d '{"code":"the-code-from-the-email"}'

Programmatic (Go)

The service call only verifies the user — it doesn't create a session by itself. Mirror what the HTTP handler does and create one explicitly right after:

user, err := auth.Services.Verify.VerifyEmail(ctx, code)
if err != nil {
    // wraps a *domain.AuthError — see Error Handling → Handling errors programmatically
}

result, err := auth.Services.Session.Create(ctx, user.ID, r.RemoteAddr, r.UserAgent())
// result.SessionToken / result.RefreshToken are the raw values — set them as cookies yourself

Client

const result = await apiRequest(API_BASE, "POST", "/auth/verify-email", { code });
// result.user.isVerified is now true, session cookies are set

For a complete email verification form with resend, see Client → Email verification.

Register via invite — requires EnableInvite: true

Two-step: look up the invite to pre-fill the form, then complete registration with it. Invite accounts are created pre-verified — there's no separate email-verification step.

GET /auth/invite/info?token=... — public lookup, used to show "you're signing up as ada@example.com" before the user types a password.

{ "email": "ada@example.com" }

POST /auth/invite/register — body { "code", "name", "password", "confirmPassword" }. code is the same raw token as token above, just renamed in the body.

{
  "user": { "...": "isVerified: true" },
  "session": { "...": "same shape as register" }
}

curl

# 1. Look up the invite
curl "https://api.myapp.com/auth/invite/info?token=THE_RAW_CODE"

# 2. Complete registration
curl -X POST https://api.myapp.com/auth/invite/register \
  -H "Content-Type: application/json" \
  -H "Origin: https://myapp.com" \
  -c cookies.txt \
  -d '{"code":"THE_RAW_CODE","name":"Ada Lovelace","password":"correct horse battery staple 1","confirmPassword":"correct horse battery staple 1"}'

Programmatic (Go)

invite, err := auth.Services.Invite.GetInviteByToken(ctx, rawToken)
// invite.Email — pre-fill the form with this

result, err := auth.Services.Invite.CompleteInviteRegistration(ctx, goauth.CompleteInviteInput{
    Code:            rawToken,
    Name:            "Ada Lovelace",
    Password:        "correct horse battery staple 1",
    ConfirmPassword: "correct horse battery staple 1",
    IP:              r.RemoteAddr,
    UserAgent:       r.UserAgent(),
})

Client

const { email } = await apiRequest(
  API_BASE, "GET", `/auth/invite/info?token=${encodeURIComponent(token)}`
);

const result = await apiRequest(API_BASE, "POST", "/auth/invite/register", {
  code: token,
  name: "Ada Lovelace",
  password,
  confirmPassword,
});

For a complete invite registration form, see Client → Invite registration.

Login

Login — POST /auth/login

Login is never disabled by RegistrationConfig — those flags only gate how an account gets created, not whether an existing one can sign in.

Request body

Response — normal success (200 OK) — identical shape to register's success response: { "user", "session" }, cookies set the same way.

Response — verification pending (200 OK) — if RequireEmailVerification: true and the account hasn't verified yet:

{
  "user": { "...": "isVerified: false" },
  "requiresVerification": true,
  "message": "Please verify your email to continue."
}

No session is issued — the credentials were correct, but that's not enough on its own.

Response — two-factor pending (200 OK) — if TwoFactorConfig.RequireEmail2FA: true, or the account has per-user 2FA on (User.TwoFactorEnabled):

{
  "user": { "...": "same shape as normal success" },
  "requiresTwoFactor": true,
  "codeSent": true,
  "challengeId": "c4a1...",
  "expiresAt": "2026-08-09T12:05:00Z",
  "message": "Two-factor code sent to your email"
}

Same shape and same binding cookie as the register case above — see Two-factor authentication to complete the flow. codeSent is false and the message changes to "A two-factor code was already sent, check your email" if the client calls Login again while a still-valid, uncapped challenge already exists — the code isn't re-mailed on every login attempt.

codeSent: false always refers to a code the mailer accepted. A login whose send fails returns email_failed (500) and leaves no challenge behind, so the next attempt mints and mails a fresh one rather than pointing at a code that was never delivered. POST /auth/2fa/resend is the exception: it refreshes the code on the existing challenge row, and a failed send there keeps the row — that row carries the lineage's attempt count, which a delete would reset. Retrying the resend re-mints on it while refreshes remain.

Errors

invalid_credentials for an email that doesn't exist at all runs comparisons against a startup-generated dummy hash in the currently configured hasher's format, so that request burns the same KDF work as a wrong-password one — see Security for why that matters.

curl

curl -X POST https://api.myapp.com/auth/login \
  -H "Content-Type: application/json" \
  -H "Origin: https://myapp.com" \
  -c cookies.txt \
  -d '{"email":"ada@example.com","password":"correct horse battery staple 1"}'

Programmatic (Go)

result, err := auth.Services.Auth.Login(ctx, goauth.LoginInput{
    Email:     "ada@example.com",
    Password:  "correct horse battery staple 1",
    IP:        r.RemoteAddr,
    UserAgent: r.UserAgent(),
})
if err != nil {
    // wraps a *domain.AuthError — see Error Handling → Handling errors programmatically
}
if result.RequiresVerification {
    // no session issued
}
if result.RequiresTwoFactor {
    // no session issued — result.TwoFactorChallenge is the challenge id,
    // result.BindingToken() is what the handler would set as a cookie
}

Client

const result = await apiRequest(API_BASE, "POST", "/auth/login", { email, password });

if (result.requiresVerification) {
  // route to a "verify your email" screen
} else if (result.requiresTwoFactor) {
  // route to a "enter your code" screen — the binding cookie is already set
  setChallengeId(result.challengeId);
} else {
  setUser(result.user); // cookies are already set
}

For a complete login form with branching logic and error handling, see Client → Login.

Two-factor authentication

Turned on globally with TwoFactorConfig.RequireEmail2FA (mandatory for every account) or per-user via POST /auth/2fa/enable (opt-in, unless RequireEmail2FA is on, in which case per-user toggling is rejected). Either way, Login/Register/POST /auth/invite/register return the gated {user, requiresTwoFactor: true, codeSent, challengeId, expiresAt, message} shape shown above instead of a session, plus a binding cookie. Full config reference on Configuration; the risk trade-offs behind this design are on Security.

Verifying the code — POST /auth/2fa/verify

Completes any of the gated flows above — it doesn't need to know which one started the challenge. Body: { "challengeId": "...", "code": "..." }. The binding cookie set alongside the gated response must be present on this request (unless TwoFactorConfig.DisableChallengeBinding is set); a missing or mismatched cookie is rejected the same way a wrong code is, without revealing which.

{
  "user": { "...": "same shape as login" },
  "session": { "...": "same shape as login" }
}

Session and refresh cookies are set here, not on the original gated response — until this call succeeds, nothing has been issued.

curl

curl -X POST https://api.myapp.com/auth/2fa/verify \
  -H "Content-Type: application/json" \
  -H "Origin: https://myapp.com" \
  -b cookies.txt -c cookies.txt \
  -d '{"challengeId":"c4a1...","code":"482913"}'

-b cookies.txt matters here — it's what sends the binding cookie saved from the login/register response back to the server.

Programmatic (Go)

result, err := auth.Services.TwoFactor.Verify(
    ctx, challengeID, bindingToken, code, r.RemoteAddr, r.UserAgent(),
)
if err != nil {
    // wraps a *domain.AuthError — see Error Handling → Handling errors programmatically
}
// result.User is the authenticated user; result.SessionToken / result.RefreshToken
// are the raw values — set them as cookies yourself

Client

const result = await apiRequest(API_BASE, "POST", "/auth/2fa/verify", {
  challengeId,
  code,
});
setUser(result.user); // cookies are already set

For a complete two-factor form with resend, see Client → Two-factor.

Resending the code — POST /auth/2fa/resend

Body: { "challengeId": "..." }. Refreshes the code on the same challenge — challengeId doesn't change, so the client doesn't need to update it. Capped at 3 resends per challenge; combined with the 5-guess attempt cap, this is what keeps the guess budget bounded rather than resettable on demand.

An unknown or binding-mismatched challengeId gets the same generic 200 as a real resend (challenge_not_found, "If the challenge is valid, a new code has been sent") — the endpoint never confirms or denies which challenge IDs are real.

curl

curl -X POST https://api.myapp.com/auth/2fa/resend \
  -H "Content-Type: application/json" \
  -H "Origin: https://myapp.com" \
  -b cookies.txt -c cookies.txt \
  -d '{"challengeId":"c4a1..."}'

Programmatic (Go)

result, err := auth.Services.TwoFactor.Resend(ctx, challengeID, bindingToken)

Client

await apiRequest(API_BASE, "POST", "/auth/2fa/resend", { challengeId });

For a complete two-factor form with resend, see Client → Two-factor.

For enabling and disabling 2FA, see User management → Two-factor.

Logout

Logout — POST /auth/logout

Takes no body and requires an authenticated session. It revokes that session server-side, then clears both session cookies and rotates the CSRF cookie. If server-side revocation fails, it returns 500 internal_error and does not clear the cookies; the client must not discard its local authenticated state or redirect as though logout succeeded.

{ "message": "Logged out" }

curl

curl -X POST https://api.myapp.com/auth/logout \
  -H "Origin: https://myapp.com" \
  -b cookies.txt -c cookies.txt

Programmatic (Go)

The HTTP handler revokes by the raw session token — the same value stored in the cookie — not by session ID:

err := auth.Services.Session.Revoke(ctx, sessionToken) // sessionToken is the raw value from the cookie, not the session's ID

If you only have the session ID instead (e.g. an admin ending one specific session — see Routes → Sessions), use auth.Services.Auth.Logout(ctx, sessionID) instead — same effect, looked up differently.

Client

await apiRequest(API_BASE, "POST", "/auth/logout");
setUser(null);
window.location.href = "/login";

For a complete logout button with error handling, see Client → Logout.

For account deletion and name changes, see User management.

Next

• User management — name changes, 2FA toggle, and account deletion
• Security — password changes and verification resend
• Admin — admin login and platform-wide user management
• Routes — every other endpoint, including sessions, password, and account management
• Error Handling — the full error code list
• Providers — OAuth setup for GitHub and Google