Authentication Endpoints

Endpoints for user registration, login, password management, and social OAuth.

Register

POST /api/v1/auth/register

Body

{
  "email": "user@example.com",
  "password": "supersecret",
  "name": "Jane Doe"
}

Response 201

{
  "data": {
    "user": {
      "id": "usr_01j...",
      "email": "user@example.com",
      "name": "Jane Doe",
      "createdAt": "2026-03-18T00:00:00Z"
    },
    "accessToken": "eyJ...",
    "refreshToken": "rt_..."
  }
}

Login

POST /api/v1/auth/login

Body

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

Response 200

{
  "data": {
    "accessToken": "eyJ...",
    "refreshToken": "rt_...",
    "expiresIn": 900
  }
}

Refresh Token

POST /api/v1/auth/refresh

Body

{
  "refreshToken": "rt_..."
}

Response 200

{
  "data": {
    "accessToken": "eyJ...",
    "expiresIn": 900
  }
}

Logout

POST /api/v1/auth/logout

Headers

• Authorization: Bearer <accessToken>

Body

{
  "refreshToken": "rt_..."
}

Response 204

No body.

Forgot Password

POST /api/v1/auth/forgot-password

Body

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

Response 200

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

Reset Password

POST /api/v1/auth/reset-password

Body

{
  "token": "reset_...",
  "password": "newpassword"
}

Response 200

{
  "data": {
    "message": "Password reset successfully."
  }
}

Social OAuth — Redirect

GET /api/v1/auth/social/{provider}

Supported providers: google, github, microsoft

Redirects the user to the provider's OAuth consent page.

Query Parameters

• redirectUri — URI to redirect after auth
• state — CSRF token (recommended)

Social OAuth — Callback

GET /api/v1/auth/social/{provider}/callback

Called by the provider after consent. Returns tokens.

Response 200

{
  "data": {
    "accessToken": "eyJ...",
    "refreshToken": "rt_...",
    "user": { "id": "usr_01j...", "email": "user@example.com" }
  }
}