Users and Companies API — Multi-tenant Management

Stay Sidekick uses a two-level multi-tenant model: companies (empresas) are the top-level tenants, each containing one or more users (usuarios). Superadmins can manage any company and its users. Admins can only manage users within their own company. A company’s max_usuarios limit is enforced at creation time and cannot be exceeded. Valid user roles are admin and operativo. The first user created for a company is automatically assigned the admin role.

All endpoints require Authorization: Bearer <token>. POST, PATCH, and DELETE requests also require the X-CSRF-Token header.

GET /api/usuarios

Lists all users belonging to the target company, along with the company’s maximum user allowance. Auth required: Yes | Role: admin or superadmin

Superadmins can append ?empresa_id=<uuid> to query users from any company. Admins always see their own company’s users only.

Query Parameters

empresa_id

string

(Superadmin only) UUID of the company to query. Ignored for non-superadmin callers.

Response

boolean

required

true

usuarios

array

required

Array of user objects.

Show User object

string

UUID of the user.

string

User’s email address.

rol

string

User’s role: admin or operativo.

activo

boolean

Whether the account is active.

created_at

string

ISO 8601 creation timestamp.

max_usuarios

integer

required

Maximum number of users allowed for the company.

Example

curl https://api.example.com/api/usuarios \
  -H "Authorization: Bearer $TOKEN"

{
  "ok": true,
  "usuarios": [
    {
      "id": "11111111-0000-4000-a000-000000000001",
      "email": "admin@miempresa.com",
      "rol": "admin",
      "activo": true,
      "created_at": "2024-01-15T10:00:00+00:00"
    }
  ],
  "max_usuarios": 10
}

POST /api/usuarios

Creates a new user for the target company. A secure temporary password is generated automatically and returned in the response — it must be delivered to the new user out-of-band. The user should change it on first login. Auth required: Yes | Role: admin or superadmin

Request

string

required

Email address of the new user. Must be a valid email. Max 254 characters. Normalised to lowercase.

rol

string

required

Role to assign. One of: admin, operativo.

Response

201 Created

boolean

required

true

usuario

object

required

The newly created user object.

password_temporal

string

required

Auto-generated temporary password. Show this to the admin creating the account — it will not be retrievable again.

Example

curl -X POST https://api.example.com/api/usuarios \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{"email": "operario@miempresa.com", "rol": "operativo"}'

{
  "ok": true,
  "usuario": {
    "id": "22222222-0000-4000-a000-000000000002",
    "email": "operario@miempresa.com",
    "rol": "operativo",
    "activo": true,
    "created_at": "2024-08-15T09:30:00+00:00"
  },
  "password_temporal": "Xk9!mPq2wZ"
}

Store or communicate the password_temporal immediately. It is generated once and not stored in plain text — there is no way to retrieve it again. Use PATCH /api/usuarios/<id>/contrasena to issue a new one if needed.

DELETE /api/usuarios/<id>

Permanently deletes a user from the company. A user cannot delete their own account. Auth required: Yes | Role: admin or superadmin

Path Parameters

string

required

UUID of the user to delete.

Response

200 OK — {"ok": true} 404 Not Found — user not found or belongs to a different company. 422 Unprocessable Entity — e.g., attempting to self-delete.

Example

curl -X DELETE https://api.example.com/api/usuarios/22222222-0000-4000-a000-000000000002 \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>"

PATCH /api/usuarios/<id>

Changes the role of an existing user. Auth required: Yes | Role: admin or superadmin

Path Parameters

string

required

UUID of the user whose role should change.

Request

rol

string

required

New role. One of: admin, operativo.

Response

boolean

required

true

usuario

object

required

The updated user object.

Example

curl -X PATCH https://api.example.com/api/usuarios/22222222-0000-4000-a000-000000000002 \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{"rol": "admin"}'

{
  "ok": true,
  "usuario": {
    "id": "22222222-0000-4000-a000-000000000002",
    "email": "operario@miempresa.com",
    "rol": "admin",
    "activo": true,
    "created_at": "2024-08-15T09:30:00+00:00"
  }
}

PATCH /api/usuarios/<id>/contrasena

Generates and sets a new temporary password for the specified user, overwriting the previous one. Use this when a user is locked out or has forgotten their credentials. Auth required: Yes | Role: admin or superadmin

Path Parameters

string

required

UUID of the user whose password should be reset.

Response

boolean

required

true

password_temporal

string

required

The newly generated temporary password. Display it to the admin immediately.

Example

curl -X PATCH https://api.example.com/api/usuarios/22222222-0000-4000-a000-000000000002/contrasena \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>"

{
  "ok": true,
  "password_temporal": "Tz4#nRv8kL"
}

GET /api/empresas

Lists all active companies on the platform, ordered alphabetically by name. Auth required: Yes | Role: superadmin

Response

boolean

required

true

empresas

array

required

Array of company objects.

Show Company object

string

UUID of the company.

nombre

string

Company display name.

string

Primary contact email.

Example

curl https://api.example.com/api/empresas \
  -H "Authorization: Bearer $TOKEN"

{
  "ok": true,
  "empresas": [
    {"id": "aaaaaaaa-0000-4000-a000-000000000001", "nombre": "Apartamentos Sol", "email": "info@sol.com"},
    {"id": "bbbbbbbb-0000-4000-a000-000000000002", "nombre": "Sun Rentals", "email": "ops@sunrentals.es"}
  ]
}

POST /api/empresas

Creates a new company tenant. A welcome email is sent to the company’s email address on successful creation. Auth required: Yes | Role: superadmin

Request

nombre

string

required

Company display name. 1–200 characters.

string

required

Primary contact email address. Must be unique across all companies.

Response

201 Created

boolean

required

true

empresa

object

required

The newly created company object (id, nombre, email).

Example

curl -X POST https://api.example.com/api/empresas \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{"nombre": "Mar Rentals SL", "email": "admin@mar-rentals.com"}'

{
  "ok": true,
  "empresa": {
    "id": "cccccccc-0000-4000-a000-000000000003",
    "nombre": "Mar Rentals SL",
    "email": "admin@mar-rentals.com"
  }
}

DELETE /api/empresas/<id>

Permanently deletes a company and all of its associated data in cascade (users, apartments, templates, integrations, etc.). This action is irreversible. Auth required: Yes | Role: superadmin

Path Parameters

string

required

UUID of the company to delete.

Response

200 OK

boolean

required

true

mensaje

string

required

Human-readable confirmation message.

404 Not Found — company not found.

Example

curl -X DELETE https://api.example.com/api/empresas/cccccccc-0000-4000-a000-000000000003 \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>"

{
  "ok": true,
  "mensaje": "Empresa eliminada correctamente."
}

Deleting a company cascades to all associated records: users, apartments, PMS/AI configurations, vault templates, heat map thresholds, and Google OAuth tokens. There is no soft-delete for companies — data cannot be recovered after this call.

Overview

Endpoints

Users and Companies API — Multi-tenant Management

GET /api/usuarios

Query Parameters

Response

Example

POST /api/usuarios

Request

Response

Example

DELETE /api/usuarios/<id>

Path Parameters

Response

Example

PATCH /api/usuarios/<id>

Path Parameters

Request

Response

Example

PATCH /api/usuarios/<id>/contrasena

Path Parameters

Response

Example

GET /api/empresas

Response

Example

POST /api/empresas

Request

Response

Example

DELETE /api/empresas/<id>

Path Parameters

Response

Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/usuarios

​Query Parameters

​Response

​Example

​POST /api/usuarios

​Request

​Response

​Example

​DELETE /api/usuarios/<id>

​Path Parameters

​Response

​Example

​PATCH /api/usuarios/<id>

​Path Parameters

​Request

​Response

​Example

​PATCH /api/usuarios/<id>/contrasena

​Path Parameters

​Response

​Example

​GET /api/empresas

​Response

​Example

​POST /api/empresas

​Request

​Response

​Example

​DELETE /api/empresas/<id>

​Path Parameters

​Response

​Example

Build docs developers (and LLMs) love

GET /api/usuarios

Query Parameters

Response

Example

POST /api/usuarios

Request

Response

Example

DELETE /api/usuarios/<id>

Path Parameters

Response

Example

PATCH /api/usuarios/<id>

Path Parameters

Request

Response

Example

PATCH /api/usuarios/<id>/contrasena

Path Parameters

Response

Example

GET /api/empresas

Response

Example

POST /api/empresas

Request

Response

Example

DELETE /api/empresas/<id>

Path Parameters

Response

Example