API Endpoints
All paths are prefixed with your BasePath (default: /auth). Endpoints depend on which modules you register.
Core Module (auto-registered)​
POST /signup — Register a new user
Request:
{
"email": "user@example.com",
"password": "SecurePassword123!",
"first_name": "John",
"last_name": "Doe",
"username": "johndoe",
"phone_number": "+1234567890",
"extended_attributes": {"company": "Acme Inc"}
}
Success Response 200:
{
"message": "User registered successfully",
"user": {
"id": "uuid",
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe",
"email_verified": false
},
"token": "eyJhbGciOi...",
"refresh_token": "eyJhbGciOi..."
}
Error 400: "email already exists" or validation errors.
GET /me — Get current user Auth
Headers: Authorization: Bearer <access_token>
Response 200:
{
"id": "uuid",
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe"
}
GET /profile — Get full profile Auth
Headers: Authorization: Bearer <access_token>
Response 200:
{
"id": "uuid",
"email": "user@example.com",
"username": "johndoe",
"first_name": "John",
"last_name": "Doe",
"phone_number": "+1234567890",
"email_verified": true,
"phone_number_verified": false,
"extended_attributes": {"company": "Acme Inc"},
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-15T00:00:00Z"
}
PUT /profile — Update profile Auth
Headers: Authorization: Bearer <access_token>
Request:
{
"first_name": "Jane",
"phone_number": "+9876543210",
"extended_attributes": {"role": "Manager"}
}
PUT /change-password — Change password Auth
Headers: Authorization: Bearer <access_token>
Request:
{
"old_password": "OldPassword123!",
"new_password": "NewPassword456!"
}
POST /forgot-password — Request password reset
Request:
{"email": "user@example.com"}
Response 200:
{"message": "Password reset email sent"}
POST /reset-password — Reset with token
Request:
{
"token": "reset-token-from-email",
"new_password": "NewPassword456!"
}
POST /send-verification-email — Send verification email Auth
Headers: Authorization: Bearer <access_token>
Sends a verification link to the user's email address.
GET /verify-email?token=... — Verify email
Called from the email link. Redirects to FrontendConfig.VerifyEmailCallbackPath with ?status=success or ?status=error.
Falls back to JSON response if FrontendConfig is not set.
POST /send-verification-phone — Send phone verification SMS Auth
Requires the Notification module with an SMS sender configured.
POST /verify-phone — Verify phone Auth
Request:
{"code": "123456"}
POST /availability/email — Check email availability
Request:
{"email": "newuser@example.com"}
Response:
{"available": true, "field": "email"}
POST /availability/username — Check username availability
Request: {"username": "johndoe"}
POST /availability/phone — Check phone availability
Request: {"phone_number": "+1234567890"}
Session Module​
Requires session.New(...). Mutually exclusive with Stateless.
POST /login — Login (create session)
Request:
{
"email": "user@example.com",
"password": "SecurePassword123!"
}
Response 200:
{
"message": "Login successful",
"user": {"id": "uuid", "email": "user@example.com"},
"token": "eyJhbGciOi...",
"refresh_token": "eyJhbGciOi..."
}
POST /logout — Logout Auth
Ends the current session.
POST /refresh — Refresh tokens
Request:
{"refresh_token": "eyJhbGciOi..."}
GET /sessions — List sessions Auth
Requires EnableSessionManagement: true.
Response 200:
{
"sessions": [
{
"id": "session-uuid",
"ip_address": "192.168.1.1",
"user_agent": "Mozilla/5.0...",
"created_at": "2025-01-01T00:00:00Z"
}
]
}
DELETE /sessions/{id} — Revoke session Auth
Revokes a specific session by ID.
DELETE /sessions — Revoke all sessions Auth
Revokes all sessions except the current one.
Stateless Module​
Default if no auth module registered. Or register explicitly with stateless.New(...).
POST /login — Login (JWT tokens)
Request:
{
"email": "user@example.com",
"password": "SecurePassword123!"
}
Response 200:
{
"message": "Login successful",
"user": {"id": "uuid", "email": "user@example.com"},
"token": "eyJhbGciOi...",
"refresh_token": "eyJhbGciOi..."
}
POST /logout — Blacklist token Auth
Blacklists the current access token.
POST /refresh — Refresh tokens
Returns new access token. Optionally rotates refresh token if RefreshTokenRotation: true.
Two-Factor Module​
Requires twofactor.New(...).
POST /2fa/setup — Start 2FA setup Auth
Response 200:
{
"secret": "JBSWY3DPEHPK3PXP",
"qr_url": "otpauth://totp/MyApp:user@example.com?secret=...",
"backup_codes": ["12345678", "87654321", "..."]
}
POST /2fa/verify — Verify and enable 2FA Auth
Request:
{"code": "123456"}
POST /2fa/disable — Disable 2FA Auth
Request:
{"code": "123456"}
GET /2fa/status — Get 2FA status Auth
Response 200:
{"enabled": true, "verified": true, "method": "totp"}
POST /2fa/verify-login — Complete login with 2FA
Called after login returns requires_2fa: true.
Request:
{
"temp_token": "temporary-2fa-token",
"code": "123456"
}
Response 200: Returns auth tokens.
OAuth Module​
Requires oauth.New(...) with configured providers and APIURL set.
GET /oauth/{provider} — Start OAuth flow
Redirects to the OAuth provider's consent screen.
Providers: google, github, facebook, microsoft, apple, discord
GET /oauth/{provider}/callback — OAuth callback
Handles provider callback. Creates/links user, then:
- Redirects to
DefaultRedirectURL#access_token=xxx&refresh_token=xxx - Or returns JSON if no redirect URL configured
DELETE /oauth/{provider} — Unlink provider Auth
Unlinks an OAuth provider from the user's account.
GET /oauth/providers — List available providers
Response 200:
{"providers": ["google", "github"]}
GET /oauth/linked — List linked providers Auth
Response 200:
{"providers": [{"provider": "google", "email": "user@gmail.com"}]}
Admin Module​
Requires admin.New(...). All routes require auth + admin middleware.
GET /admin/users — List users Admin
Query: ?page=1&limit=20
Response 200:
{
"users": [{"id": "uuid", "email": "user@example.com", "active": true}],
"total": 100,
"page": 1
}
GET /admin/users/{id} — Get user Admin
Returns full user details.
PUT /admin/users/{id} — Update user Admin
Request:
{"active": false, "role": "admin"}
DELETE /admin/users/{id} — Delete user Admin
Permanently deletes the user.
Audit Module​
Requires audit.New(...).
GET /me/audit — My audit logs Auth
Returns the authenticated user's audit trail.
GET /me/audit/logins — My login history Auth
Returns login events for the authenticated user.
GET /me/audit/changes — My profile changes Auth
Returns profile update events.
GET /me/audit/security — My security events Auth
Returns security-related events (2FA changes, password changes, etc.).
GET /admin/audit — All audit logs Admin
Returns all audit logs across all users.
GET /admin/audit/users/{id} — User audit logs Admin
Returns audit logs for a specific user.
GET /admin/audit/actions/{action} — Logs by action Admin
Returns audit logs filtered by action type.
CSRF Module​
Requires csrf.New(...).
GET /csrf-token — Get CSRF token
Response 200:
{"csrf_token": "hmac-signed-token"}
Also sets a __goauth_csrf cookie. Include the token in X-CSRF-Token header for protected methods (POST, PUT, DELETE, PATCH).
Magic Link Module​
Requires magiclink.New(...) and the Notification module.
POST /magic-link/send — Send magic link
Request:
{"email": "user@example.com"}
Sends an email with a magic link. If AutoRegister: true, creates a new user if email doesn't exist.
GET /magic-link/verify — Verify magic link
Query: ?token=magic-link-token
Verifies the token and either:
- Redirects to
CallbackURL#access_token=xxx&refresh_token=xxx - Or returns JSON auth response
POST /magic-link/verify-code — Verify by code
Request:
{"email": "user@example.com", "code": "123456"}
For mobile apps — verifies using the numeric code from the email.
POST /magic-link/resend — Resend magic link
Request:
{"email": "user@example.com"}
Authentication​
Protected endpoints require:
Authorization: Bearer <access_token>
Get tokens from the login endpoint. Refresh expired tokens via /refresh.
Admin endpoints additionally require admin privileges on the user account.