Auth API¶

Authentication endpoints for local email/password login, Google OAuth2, token management, password reset, and account verification.

Public endpoints (no Bearer token required): Register, Login, Reset Password, Update Password, Confirm Account, Resend Confirm, OAuth Initiate, OAuth Callback.

Protected endpoints (Bearer token required): Refresh Token, Revoke Token.

Error responses: All errors return a flat JSON body — there is no code field and no nested error object:

{
  "success": false,
  "status": 400,
  "message": "..."
}

Register¶

POST /auth/register

Creates a new local account with email and password. Returns a JWT token and the account object.

Request Body¶

Example Request¶

{
  "email": "newuser@example.com",
  "password": "SecureP@ssw0rd!",
  "name": "New User"
}

Response¶

{
  "success": true,
  "status": 200,
  "data": {
    "access_token": "eyJ...",
    "refresh_token": "eyJ...",
    "account": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "newuser@example.com",
      "name": "New User",
      "verified": false,
      "enabled": true
    }
  }
}

Possible Errors¶

Login¶

POST /auth/login

Authenticates with email and password credentials. Returns a JWT token (60-minute TTL) and the account object.

Request Body¶

Example Request¶

{
  "email": "user@email.com",
  "password": "password"
}

Response¶

{
  "success": true,
  "status": 200,
  "data": {
    "access_token": "eyJ...",
    "refresh_token": "eyJ...",
    "account": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@email.com",
      "name": "...",
      "verified": true,
      "enabled": true
    }
  }
}

Possible Errors¶

Refresh Token¶

POST /auth/refresh

Exchanges a valid Bearer token for a new JWT with renewed expiry (60 minutes from now). No request body required — the current token in the Authorization header provides identity.

Auth required: Bearer token

Example Request¶

{}

Request Headers¶

Authorization: Bearer eyJ...
Content-Type: application/json

Response¶

{
  "success": true,
  "status": 200,
  "data": {
    "access_token": "eyJ...",
    "refresh_token": "eyJ..."
  }
}

Possible Errors¶

Reset Password (Request)¶

POST /auth/reset-password

Requests a password reset email for the given address. Always returns success to prevent email enumeration. The reset token (24h TTL) is logged server-side and included in the email.

Request Body¶

Example Request¶

{
  "email": "user@email.com"
}

Response¶

{
  "success": true,
  "status": 200,
  "data": {
    "message": "If an account exists for this email, a reset link has been sent."
  }
}

Update Password (with Reset Token)¶

POST /auth/update-password

Sets a new password using a valid password reset token. The token must be of type PasswordReset and not expired (24h TTL).

Request Body¶

Example Request¶

{
  "token": "eyJ...",
  "password": "NewSecureP@ssw0rd!"
}

Response¶

{
  "success": true,
  "status": 200,
  "data": {
    "account_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Possible Errors¶

Confirm Account¶

POST /auth/confirm

Verifies a user's email address using a confirmation token generated during registration. The token must be of type AccountConfirm and not expired (24h TTL).

Request Body¶

Example Request¶

{
  "token": "eyJ..."
}

Response¶

{
  "success": true,
  "status": 200,
  "data": {
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "verified": true
  }
}

Possible Errors¶

Resend Confirmation Email¶

POST /auth/resend-confirm

Resends the account confirmation email for an unverified account. Silently succeeds if the account doesn't exist (anti-enumeration).

Request Body¶

Example Request¶

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

Response¶

{
  "success": true,
  "status": 200,
  "data": {
    "message": "If an unverified account exists, a new confirmation email has been sent."
  }
}

Possible Errors¶

Revoke Token (Logout)¶

POST /auth/revoke

Revokes the current JWT token, rendering it invalid for future requests. The token's session version is incremented and the auth cache is purged. Subsequent requests with the old token fail validation because the version claims no longer match the server-side state.

Auth required: Bearer token (the token being revoked)

Example Request¶

{}

Request Headers¶

Authorization: Bearer eyJ...
Content-Type: application/json

Response¶

{
  "success": true,
  "status": 200,
  "data": {
    "revoked": true
  }
}

Possible Errors¶

OAuth: Initiate Google Login¶

POST /auth/oauth/google/initiate

Starts the Google OAuth2 login flow. Generates a cryptographically random CSRF token, stores it in Redis (10-min TTL), and returns the complete Google authorization URL that the client should redirect the user to.

Request Body¶

Example Request¶

{
  "redirect_url": "http://localhost:5000/dashboard"
}

Response¶

{
  "success": true,
  "status": 200,
  "data": {
    "auth_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&response_type=code&scope=openid+email+profile&state=..."
  }
}

OAuth: Google Callback¶

GET /auth/oauth/google/callback

Read-only GET endpoint that Google redirects the user to after they complete the consent screen. Processes the authorization code, exchanges it for tokens, fetches the Google user profile, creates or links an account, and redirects the user to the client-provided redirect_url with the JWT token as a query parameter.

This is NOT a JSON endpoint — it returns a 302 Found redirect.

Query Parameters¶

Success Redirect¶

HTTP/1.1 302 Found
Location: http://localhost:5000/dashboard?token=eyJ...&refresh_token=eyJ...

Error Redirects¶

Auth Flow Summary¶