Authentication

Base path: /api/auth

All auth endpoints are public (no token required) unless explicitly marked [Auth required].

Endpoints

POST /api/auth/register

Create a new customer account.

Rate limit: 10 req / min

Request body:

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "9800000000",
  "password": "secret123",
  "password_confirmation": "secret123"
}

Response 201:

{
  "message": "Registration successful.",
  "token": "1|abc...",
  "data": {
    "id": 1,
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "9800000000",
    "avatar": null,
    "wallet_balance": "0.00",
    "is_active": true,
    "email_verified": false,
    "phone_verified": false,
    "roles": ["customer"],
    "permissions": [],
    "created_at": "2025-01-01 10:00:00"
  }
}

POST /api/auth/login

Log in with email/phone + password.

Rate limit: configurable

Request body:

{
  "email": "jane@example.com",
  "password": "secret123"
}

Tip: email field also accepts a phone number string.

Response 200:

{
  "token": "2|xyz...",
  "data": { ...UserResource... }
}

Response 403 — wrong credentials or inactive account:

{ "message": "Invalid credentials." }

POST /api/auth/otp/send

Send a one-time password via SMS or email for phone/passwordless login.

Rate limit: configurable

Request body:

{
  "identifier": "9800000000",
  "type": "sms"
}

Response 200:

{ "message": "OTP sent successfully. Please check your SMS or email." }

The OTP is never returned in the API response — only delivered out-of-band.

POST /api/auth/otp/verify

Verify OTP and receive an auth token.

Request body:

{
  "identifier": "9800000000",
  "otp": "123456",
  "type": "sms"
}

Response 200 (token issued):

{
  "message": "OTP verified.",
  "token": "3|...",
  "data": { ...UserResource... }
}

Response 200 (verified but no token — e.g., pre-registration step):

{ "message": "OTP verified." }

Response 422:

{ "message": "Invalid or expired OTP." }

GET /api/auth/social/{provider}

Get the OAuth redirect URL for social login.

Response 200:

{ "url": "https://accounts.google.com/o/oauth2/auth?..." }

Redirect the user's browser to url. After they authenticate, the provider calls back to the server and you receive a token via the callback endpoint.

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

OAuth callback — called by the provider, not by your app directly.

Returns the same token shape as /login.

GET /api/auth/me [Auth required]

Return the currently authenticated user.

Response 200:

{
  "data": { ...UserResource... }
}

POST /api/auth/logout [Auth required]

Revoke the current device token.

Response 200:

{ "message": "Logged out." }

GET /api/auth/devices [Auth required]

List all active tokens / devices for this account.

Response 200:

[
  {
    "id": 1,
    "name": "mobile_app",
    "last_used_at": "2025-01-10 08:00:00",
    "created_at": "2025-01-01 10:00:00"
  }
]

DELETE /api/auth/devices/{tokenId} [Auth required]

Revoke a specific device (remote logout).

Response 200:

{ "message": "Device revoked." }

Email Verification

After registration the user receives a verification email.

GET /api/email/verify/{id}/{hash} [Auth required]

Verify the email. This URL is delivered inside the email — the mobile app should open it via a deep-link or in-app browser.

Response 200:

{
  "message": "Email verified successfully.",
  "data": { ...UserResource... }
}

POST /api/email/verify/resend [Auth required]

Re-send the verification email.

Rate limit: 6 req / min

Response 200:

{ "message": "Verification email resent." }

UserResource — Field Reference