Authentication - Core Projects

Overview

Core Projects API uses Laravel Sanctum for authentication. Sanctum provides a lightweight authentication system for SPAs (Single Page Applications) and mobile applications. Authentication requires:

Valid employee credentials (email and password)
Active employee account with assigned cargo (role)
API token for subsequent requests

Authentication Flow

Authenticate an employee and receive an API token.

Endpoint

POST /api/login

This endpoint is currently commented out in the routes file. Based on the source code structure, the authentication is primarily handled through web sessions. For API token-based authentication, you’ll need to implement a Sanctum token endpoint.

Request Body

string

required

Employee email address (must be a valid email format)

password

string

required

Employee password

remember

boolean

default:false

Whether to remember the authentication session

Request Example

curl -X POST https://your-domain.com/api/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "password123",
    "remember": false
  }'

Response

{
  "success": true,
  "token": "1|aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890",
  "token_type": "Bearer",
  "empleado": {
    "id_empleado": 1,
    "nombre": "Juan",
    "apellido": "Pérez",
    "email": "[email protected]",
    "telefono": "+57 300 123 4567",
    "estado": true,
    "cargo": {
      "id_cargo": 1,
      "nombre": "Administrador",
      "descripcion": "Administrador del sistema"
    },
    "dependencia": {
      "id_dependencia": 1,
      "nombre": "Tecnología",
      "descripcion": "Departamento de TI"
    }
  }
}

Response Fields

Show Success Response Fields

success

boolean

required

Indicates successful authentication

token

string

required

API access token (Sanctum bearer token) to use in subsequent requests

token_type

string

required

Token type, always “Bearer”

empleado

object

required

Authenticated employee information

empleado.id_empleado

integer

required

Unique employee identifier

empleado.nombre

string

required

Employee first name

empleado.apellido

string

required

Employee last name

empleado.email

string

required

Employee email address

empleado.telefono

string

Employee phone number

empleado.estado

boolean

required

Employee active status (true = active, false = inactive)

empleado.cargo

object

required

Employee role/position information

empleado.cargo.id_cargo

integer

required

Unique role identifier

empleado.cargo.nombre

string

required

Role name (e.g., “Administrador”, “Vendedor”, “Gerente”)

empleado.dependencia

object

Employee department information

empleado.dependencia.id_dependencia

integer

Unique department identifier

empleado.dependencia.nombre

string

Department name

Using Your Token

Once authenticated, include the token in the Authorization header of all API requests:

Authorization: Bearer 1|aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890

Example Authenticated Request

curl -X GET https://your-domain.com/api/user \
  -H "Authorization: Bearer 1|aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890" \
  -H "Accept: application/json"

Get Current User

Retrieve the authenticated employee’s information.

Endpoint

GET /api/user

Headers

Authorization

string

required

Bearer token obtained from login

Response

{
  "id_empleado": 1,
  "nombre": "Juan",
  "apellido": "Pérez",
  "email": "[email protected]",
  "telefono": "+57 300 123 4567",
  "estado": true,
  "id_cargo": 1,
  "id_dependencia": 1,
  "cargo": {
    "id_cargo": 1,
    "nombre": "Administrador"
  },
  "dependencia": {
    "id_dependencia": 1,
    "nombre": "Tecnología"
  }
}

Logout

Revoke the current access token and end the session.

Endpoint

POST /api/logout

This endpoint is currently commented out in the routes file. To implement logout functionality, you’ll need to uncomment the route and ensure it revokes the current Sanctum token.

Headers

Authorization

string

required

Bearer token to revoke

Request Example

curl -X POST https://your-domain.com/api/logout \
  -H "Authorization: Bearer 1|aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890" \
  -H "Accept: application/json"

Response

200 Success

{
  "success": true,
  "message": "Sesión cerrada exitosamente"
}

Token Management

Token Expiration

By default, Sanctum tokens do not expire. The expiration is controlled in the config/sanctum.php file:

'expiration' => null,

Tokens without expiration remain valid indefinitely until explicitly revoked. Consider implementing token expiration for enhanced security.

Token Abilities

Sanctum supports token abilities (permissions). The Empleado model includes the HasApiTokens trait which enables this functionality:

use Laravel\Sanctum\HasApiTokens;

class Empleado extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
    // ...
}

Multiple Tokens

Employees can have multiple active tokens (e.g., for different devices). Each login generates a new token:

$token = $empleado->createToken('device-name');

Role-Based Access Control

The API implements role-based access control through the CheckCargo middleware. Some endpoints require specific roles (cargos):

Route::middleware(['auth:sanctum', 'cargo:Administrador,Gerente'])->group(...);

Common Roles

Administrador - Full system access
Gerente - Management access
Vendedor - Sales operations
Contador - Accounting operations

If you attempt to access an endpoint without the required role, you’ll receive a 403 Forbidden response with the message: “No tienes permiso para acceder a esta sección.”

Authentication Errors

401 Unauthenticated

Returned when no valid token is provided:

{
  "message": "Unauthenticated."
}

Common causes:

Missing Authorization header
Invalid or expired token
Token format incorrect (must be Bearer {token})

403 Forbidden

Returned when the authenticated user lacks permission:

{
  "message": "No tienes permiso para acceder a esta sección."
}

Common causes:

User’s cargo (role) doesn’t have access to the endpoint
Employee account is inactive
Employee has no cargo assigned

422 Validation Failed

Returned when login credentials fail validation:

{
  "success": false,
  "errors": {
    "email": ["El campo email es obligatorio"],
    "password": ["El campo password es obligatorio"]
  }
}

Security Best Practices

Token Storage

Store tokens securely on the client side. Never expose tokens in URLs or client-side code repositories.

HTTPS Only

Always use HTTPS in production to prevent token interception.

Token Rotation

Implement token rotation by logging out and logging in again periodically.

Scope Tokens

Use token abilities to limit what each token can access when possible.

Next Steps

Now that you’re authenticated, explore the available API endpoints:

Projects

Manage construction projects

Apartments

Manage apartments, locales, and parking

Sales

Handle sales operations

Employees

Manage employee records

Overview

Geographic Data

Projects & Properties

Sales & Clients

Organization

​Overview

​Authentication Flow

​Login

​Endpoint

​Request Body

​Request Example

​Response

​Response Fields

​Using Your Token

​Example Authenticated Request

​Get Current User

​Endpoint

​Headers

​Response

​Logout

​Endpoint

​Headers

​Request Example

​Response

​Token Management

​Token Expiration

​Token Abilities

​Multiple Tokens

​Role-Based Access Control

​Common Roles

​Authentication Errors

​401 Unauthenticated

​403 Forbidden

​422 Validation Failed

​Security Best Practices

Token Storage

HTTPS Only

Token Rotation

Scope Tokens

​Next Steps

Projects

Apartments

Sales

Employees

Build docs developers (and LLMs) love

Overview

Authentication Flow

Login

Endpoint

Request Body

Request Example

Response

Response Fields

Using Your Token

Example Authenticated Request

Get Current User

Endpoint

Headers

Response

Logout

Endpoint

Headers

Request Example

Response

Token Management

Token Expiration

Token Abilities

Multiple Tokens

Role-Based Access Control

Common Roles

Authentication Errors

401 Unauthenticated

403 Forbidden

422 Validation Failed

Security Best Practices

Next Steps