API Authentication

API – Authentication

Authentication is handled by Laravel Sanctum using opaque Bearer tokens. Tokens are issued on login or registration and must be included in the Authorization header for all protected requests.

Base path: /api/v1/auth

---

Endpoints

Method	Endpoint	Auth Required	Description
POST	/auth/login	No	Issue a token
POST	/auth/register	No	Register + issue token
POST	/auth/logout	Yes	Revoke current token
GET	/auth/user	Yes	Get authenticated user profile
PUT	/auth/user	Yes	Update authenticated user profile

---

POST /auth/login

Authenticate a user and receive an API token.

Request:

{
  "email": "user@example.com",
  "password": "password123",
  "device_name": "mobile-app"
}

Field	Type	Required	Description
email	string	Yes	User's email address
password	string	Yes	User's password
device_name	string	No	Label for the token (e.g. device name)

Response 200:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "user@example.com",
      "active_team_id": 1
    },
    "token": "1|abcdefgh...",
    "token_type": "Bearer"
  }
}

Store the token value. Include it as Authorization: Bearer {token} on all subsequent requests.

---

POST /auth/register

Register a new user and receive an API token in one step.

Request:

{
  "name": "John Doe",
  "email": "user@example.com",
  "password": "password123",
  "password_confirmation": "password123",
  "device_name": "mobile-app"
}

Field	Type	Required	Description
name	string	Yes	Full name
email	string	Yes	Unique email address
password	string	Yes	Minimum 8 characters
password_confirmation	string	Yes	Must match password
device_name	string	No	Label for the token

Response 201:

{
  "success": true,
  "message": "Registration successful",
  "data": {
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "user@example.com"
    },
    "token": "1|abcdefgh...",
    "token_type": "Bearer"
  }
}

---

POST /auth/logout

Revoke the current access token.

Headers: Authorization: Bearer {token}

Response 200:

{
  "success": true,
  "message": "Logout successful"
}

After logout the token is invalidated. The client should discard the token.

---

GET /auth/user

Get the authenticated user's profile, including active team details.

Headers: Authorization: Bearer {token}

Response 200:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "user@example.com",
    "active_team_id": 1,
    "active_team": {
      "id": 1,
      "name": "My Team"
    },
    "created_at": "2026-01-01T00:00:00.000Z"
  }
}

---

PUT /auth/user

Update the authenticated user's profile. All fields are optional; only include fields to change. To change the password, password_confirmation must be provided alongside password.

Headers: Authorization: Bearer {token}

Request:

{
  "name": "Updated Name",
  "email": "newemail@example.com",
  "password": "newpassword123",
  "password_confirmation": "newpassword123"
}

Field	Type	Required	Description
name	string	No	New display name
email	string	No	New email (must be unique)
password	string	No	New password
password_confirmation	string	Required if password present	Must match password

Response 200:

{
  "success": true,
  "message": "Profile updated successfully",
  "data": {
    "id": 1,
    "name": "Updated Name",
    "email": "newemail@example.com"
  }
}

---

cURL Examples

# Register
curl -X POST https://bills.msar.me/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "password123",
    "password_confirmation": "password123"
  }'

# Login
curl -X POST https://bills.msar.me/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "john@example.com",
    "password": "password123",
    "device_name": "api-client"
  }'

# Get profile
curl https://bills.msar.me/api/v1/auth/user \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

# Logout
curl -X POST https://bills.msar.me/api/v1/auth/logout \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

---

Error Responses

401 — Invalid credentials:

{
  "success": false,
  "message": "The provided credentials are incorrect."
}

422 — Validation error:

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password field is required."]
  }
}