Skip to main content

Auth REST API

Complete reference for all Auth wire REST endpoints.

Registration​

POST /auth/register​

Create a new user account.

curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "password": "secure-password-123",
    "name": "Alice Johnson"
  }'
FieldTypeRequiredDescription
emailstringYesUser's email address
passwordstringYesPassword (min 8 characters)
namestringNoUser's display name

Response (201):

{
  "user": {
    "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
    "email": "alice@example.com",
    "name": "Alice Johnson",
    "createdAt": "2025-01-15T10:30:00.000Z"
  },
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Login​

POST /auth/login​

Authenticate with email and password.

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "password": "secure-password-123"
  }'

Response (200):

{
  "user": { "_id": "...", "email": "alice@example.com", "name": "Alice Johnson" },
  "token": "eyJhbGci...",
  "refreshToken": "dGhpcyBpcyBh..."
}

Current User​

GET /auth/me​

Get the currently authenticated user. Requires a valid JWT in the Authorization header.

curl http://localhost:3000/auth/me \
  -H "Authorization: Bearer eyJhbGci..."

Response (200):

{
  "user": {
    "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
    "email": "alice@example.com",
    "name": "Alice Johnson",
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}

Logout​

POST /auth/logout​

Invalidate the current token.

curl -X POST http://localhost:3000/auth/logout \
  -H "Authorization: Bearer eyJhbGci..."

Response (200):

{
  "message": "Logged out successfully"
}

Refresh Token​

POST /auth/refresh​

Exchange a refresh token for a new access token.

curl -X POST http://localhost:3000/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "dGhpcyBpcyBh..."}'

Response (200):

{
  "token": "eyJhbGci...(new)",
  "refreshToken": "bmV3IHJl...(new)"
}

Change Password​

POST /auth/change-password​

Change the password for the authenticated user.

curl -X POST http://localhost:3000/auth/change-password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "currentPassword": "old-password",
    "newPassword": "new-secure-password"
  }'

Response (200):

{
  "message": "Password changed successfully"
}

Password Reset​

POST /auth/forgot-password​

Request a password reset email.

curl -X POST http://localhost:3000/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com"}'

Response (200):

{
  "message": "If that email exists, a reset link has been sent"
}

POST /auth/reset-password​

Reset password using the token from the email.

curl -X POST http://localhost:3000/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset-token-from-email",
    "password": "new-secure-password"
  }'

Response (200):

{
  "message": "Password reset successfully"
}

OAuth​

GET /auth/google​

Redirect to Google OAuth consent screen.

GET /auth/google/callback​

OAuth callback handler. Redirects to frontend with token.

GET /auth/github​

Redirect to GitHub OAuth consent screen.

GET /auth/github/callback​

OAuth callback handler. Redirects to frontend with token.

POST /auth/magic-link​

Send a magic link to the user's email.

curl -X POST http://localhost:3000/auth/magic-link \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com"}'

Response (200):

{
  "message": "Magic link sent to alice@example.com"
}

POST /auth/verify-magic-link​

Verify a magic link token.

curl -X POST http://localhost:3000/auth/verify-magic-link \
  -H "Content-Type: application/json" \
  -d '{"token": "magic-link-token"}'

Response (200):

{
  "user": { "_id": "...", "email": "alice@example.com" },
  "token": "eyJhbGci..."
}

Health​

GET /auth/health​

Check auth wire health status.

curl http://localhost:3000/auth/health

Response (200):

{
  "status": "healthy",
  "providers": ["local", "google", "github", "magic-link"]
}