API Category Guide

Why this call: Create a new public customer account and start an authenticated session immediately.

Request Fields

cURL Example

curl -X POST "https://api.auctionsguru.com/api/v1/auth/register" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Customer",
    "email": "alice@example.com",
    "password": "Password@123",
    "password_confirmation": "Password@123",
    "device_name": "Next.js Web App",
    "token_transport": "cookie"
  }'

Success Response

{
  "message": "Registration successful.",
  "data": {
    "user": {
      "name": "Alice Customer",
      "email": "alice@example.com",
      "avatar_url": null,
      "email_verified_at": null
    },
    "access_token": "<jwt-access-token>",
    "token_type": "Bearer",
    "expires_in": 900,
    "refresh_token": null,
    "refresh_token_expires_at": "2026-05-04T12:00:00Z",
    "refresh_token_transport": "cookie"
  }
}

Common Failures

Cookie transport stores the refresh token as a secure cookie. JSON transport returns it in data.refresh_token. Cross-site browser apps such as Vercel should use json.

Why this call: Authenticate an existing customer account and receive fresh access and refresh tokens.

Request Fields

cURL Example

curl -X POST "https://api.auctionsguru.com/api/v1/auth/login" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "password": "Password@123",
    "token_transport": "json",
    "device_name": "Android App"
  }'

Same-site Next.js Fetch Example

const response = await fetch('https://api.auctionsguru.com/api/v1/auth/login', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  credentials: 'include',
  body: JSON.stringify({
    email: 'alice@example.com',
    password: 'Password@123',
    token_transport: 'cookie'
  })
});

Cross-site Browser Fetch Example

const response = await fetch('https://api.auctionsguru.com/api/v1/auth/login', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'alice@example.com',
    password: 'Password@123',
    token_transport: 'json',
    device_name: 'Vercel Web App'
  })
});

Success Response

{
  "message": "Login successful.",
  "data": {
    "user": {
      "name": "Alice Customer",
      "email": "alice@example.com",
      "avatar_url": null,
      "email_verified_at": null
    },
    "access_token": "<jwt-access-token>",
    "token_type": "Bearer",
    "expires_in": 900,
    "refresh_token": "<refresh-token>",
    "refresh_token_expires_at": "2026-05-04T12:00:00Z",
    "refresh_token_transport": "json"
  }
}

Common Failures

A successful login updates the user's last_login_at timestamp.

Why this call: Rotate the refresh token and get a new access token without asking the user to log in again.

Request Fields

cURL Example for JSON Transport

curl -X POST "https://api.auctionsguru.com/api/v1/auth/refresh" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "<refresh-token>",
    "token_transport": "json"
  }'

Same-site Next.js Fetch Example for Cookie Transport

const response = await fetch('https://api.auctionsguru.com/api/v1/auth/refresh', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  credentials: 'include',
  body: JSON.stringify({
    token_transport: 'cookie'
  })
});

Cross-site Browser Fetch Example for JSON Transport

const response = await fetch('https://api.auctionsguru.com/api/v1/auth/refresh', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    refresh_token: refreshToken,
    token_transport: 'json'
  })
});

Success Response

{
  "message": "Token refreshed successfully.",
  "data": {
    "user": {
      "name": "Alice Customer",
      "email": "alice@example.com",
      "avatar_url": null,
      "email_verified_at": null
    },
    "access_token": "<new-jwt-access-token>",
    "token_type": "Bearer",
    "expires_in": 900,
    "refresh_token": "<new-refresh-token>",
    "refresh_token_expires_at": "2026-05-04T12:20:00Z",
    "refresh_token_transport": "json"
  }
}

Common Failures

If refresh succeeds, discard the old refresh token immediately. Reusing it later will fail.

Why this call: End the current authenticated session by revoking the current refresh token and blacklisting the current access token.

Request Fields

cURL Example for JSON Transport

curl -X POST "https://api.auctionsguru.com/api/v1/auth/logout" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "<refresh-token>"
  }'

Next.js Fetch Example for Cookie Transport

await fetch('https://api.auctionsguru.com/api/v1/auth/logout', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  credentials: 'include'
});

Success Response

{
  "message": "Logged out successfully."
}

Common Failures

Why this call: Start the password reset email flow without revealing whether the email exists.

Request Fields

cURL Example

curl -X POST "https://api.auctionsguru.com/api/v1/auth/forgot-password" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com"
  }'

Success Response

{
  "message": "If your email address exists in our system, you will receive a password reset link shortly."
}

Common Failures

The same message is returned for known and unknown emails, which helps prevent account enumeration.

Why this call: Complete the password reset after the user receives the reset token from the email link.

Request Fields

cURL Example

curl -X POST "https://api.auctionsguru.com/api/v1/auth/reset-password" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "token": "<reset-token-from-email>",
    "password": "NewPassword@123",
    "password_confirmation": "NewPassword@123"
  }'

Success Response

{
  "message": "Password has been reset successfully."
}

Common Failures

A successful reset revokes all refresh tokens and invalidates older access tokens, so every device must log in again.

Why this call: Retrieve the current authenticated customer's profile details.

cURL Example

curl -X GET "https://api.auctionsguru.com/api/v1/me" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt-access-token>"

Next.js Fetch Example

const response = await fetch('https://api.auctionsguru.com/api/v1/me', {
  headers: {
    'Accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  }
});

Success Response

{
  "message": "Profile retrieved successfully.",
  "data": {
    "user": {
      "name": "Alice Customer",
      "email": "alice@example.com",
      "avatar_url": "https://api.auctionsguru.com/storage/avatars/alice.jpg",
      "email_verified_at": null
    }
  }
}

Common Failures

Why this call: Update the current user's profile fields without changing the password.

Request Fields

cURL Example

curl -X PATCH "https://api.auctionsguru.com/api/v1/me" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Updated",
    "email": "alice.updated@example.com"
  }'

Success Response

{
  "message": "Profile updated successfully.",
  "data": {
    "user": {
      "name": "Alice Updated",
      "email": "alice.updated@example.com",
      "avatar_url": null,
      "email_verified_at": null
    }
  }
}

Common Failures

If the email value changes, the backend lowercases it and clears email_verified_at.

Why this call: Change the current user's password while authenticated.

Request Fields

cURL Example

curl -X PUT "https://api.auctionsguru.com/api/v1/me/password" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "Password@123",
    "password": "NewPassword@123",
    "password_confirmation": "NewPassword@123"
  }'

Success Response

{
  "message": "Password changed successfully. Please log in again on all devices."
}

Common Failures

This endpoint revokes all refresh tokens and invalidates existing access tokens across devices.

Why this call: Upload or replace the current user's avatar and receive the public avatar URL.

Request Fields

cURL Example

curl -X POST "https://api.auctionsguru.com/api/v1/me/avatar" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt-access-token>" \
  -F "avatar=@/absolute/path/to/avatar.jpg"

Next.js Fetch Example

const formData = new FormData();
formData.append('avatar', file);

const response = await fetch('https://api.auctionsguru.com/api/v1/me/avatar', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: formData
});

Success Response

{
  "message": "Avatar uploaded successfully.",
  "data": {
    "user": {
      "name": "Alice Customer",
      "email": "alice@example.com",
      "avatar_url": "https://api.auctionsguru.com/storage/avatars/abc123.jpg",
      "email_verified_at": null
    }
  }
}

Common Failures

Uploading a new avatar replaces the old stored avatar file when one already exists.