Super Admin: Router and API Key Management Endpoints

Routers are the physical MikroTik devices that serve as WiFi hotspot gateways for each tenant company. When a router is created, the API automatically generates a JWT-based API Key (prefixed with jwt_) that the captive portal uses to authenticate payment and hotspot creation requests. The full API Key is only returned at creation or regeneration time — it is never stored in plain text. All endpoints in this section require Authorization: Bearer <session_token> for a user with the super_admin role.

The api_key field in the router creation and regeneration responses is shown only once. Store it securely immediately after the request. It cannot be retrieved again — only revoked and replaced.

POST /admin/empresas//routers

Creates a new router for the specified company and automatically generates a JWT API Key. The full jwt_ token is returned in the response body and must be delivered to the client for use in their captive portal.

cURL

curl -X POST "https://api.example.com/admin/empresas/EMP_3A9F1C0B2D/routers" \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "empresa_id": "EMP_3A9F1C0B2D",
    "nombre": "Router Principal",
    "host": "192.168.88.1",
    "puerto": 8728,
    "usuario": "admin",
    "password": "secure_password",
    "ubicacion": "Lobby Piso 1"
  }'

Path Parameters

empresa_id

string

required

Company ID that will own this router, e.g. EMP_3A9F1C0B2D. Must be an existing active company.

Request Body

empresa_id

string

required

Must match the empresa_id path parameter.

nombre

string

required

Display name for the router, e.g. "Router Principal".

host

string

required

IP address or hostname of the MikroTik device, e.g. "192.168.88.1".

puerto

integer

default:"8728"

MikroTik API port. Default is 8728 (plaintext API). Use 8729 for encrypted API-SSL.

usuario

string

required

MikroTik API username.

password

string

required

MikroTik API password. Stored directly in the database (password_encrypted column) and used by the server to connect to the router.

ubicacion

string

Optional human-readable physical location, e.g. "Lobby Piso 1".

Response

string

required

Auto-generated router ID in the format RTR_ + 8 uppercase hex characters, e.g. RTR_A1B2C3D4.

empresa_id

string

required

Company that owns this router.

nombre

string

required

Router display name.

host

string

required

MikroTik device IP/hostname.

puerto

integer

required

API port number.

ubicacion

string

Physical location, or null if not provided.

activo

boolean

required

Always true on creation.

api_key

string

required

The full JWT API Key — shown only once. Starts with jwt_. Deliver this to the client for use in their captive portal’s X-API-Key header.

api_key_info

object

required

Show api_key_info fields

key_id

string

Unique key identifier, e.g. "key_a1b2c3d4e5f6g7h8".

issued_at

string (ISO 8601)

When the key was generated.

expires_at

string (ISO 8601)

When the key expires (typically 1 year from creation).

type

string

Always "router_api_key".

creado_en

string (ISO 8601)

required

Router creation timestamp.

Example Response

{
  "id": "RTR_A1B2C3D4",
  "empresa_id": "EMP_3A9F1C0B2D",
  "nombre": "Router Principal",
  "host": "192.168.88.1",
  "puerto": 8728,
  "ubicacion": "Lobby Piso 1",
  "activo": true,
  "api_key": "jwt_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJrZXlfYTFiMmMzZDRlNWY2ZzdoOCIsImlzcyI6Im1pa3JvdGlrLXBheW1lbnQtYXBpIiwic3ViIjoiUlRSX0ExQjJDM0Q0IiwiZW1wcmVzYSI6IkVNUF8zQTlGMUMwQjJEIn0.signature",
  "api_key_info": {
    "key_id": "key_a1b2c3d4e5f6g7h8",
    "issued_at": "2025-01-15T09:00:00",
    "expires_at": "2026-01-15T09:00:00",
    "type": "router_api_key"
  },
  "creado_en": "2025-01-15T09:00:00.123456"
}

GET /admin/empresas//routers

Lists all routers belonging to a company. Does not include API Key values.

cURL

curl -X GET "https://api.example.com/admin/empresas/EMP_3A9F1C0B2D/routers" \
  -H "Authorization: Bearer <session_token>"

Path Parameters

empresa_id

string

required

Company ID to list routers for.

Response

Returns an array of RouterResponse objects (without api_key).

Example Response

[
  {
    "id": "RTR_A1B2C3D4",
    "empresa_id": "EMP_3A9F1C0B2D",
    "nombre": "Router Principal",
    "host": "192.168.88.1",
    "puerto": 8728,
    "ubicacion": "Lobby Piso 1",
    "activo": true,
    "creado_en": "2025-01-15T09:00:00"
  }
]

GET /admin/empresas//routers/

Returns detailed information for a specific router. Verifies the router belongs to the specified company.

cURL

curl -X GET "https://api.example.com/admin/empresas/EMP_3A9F1C0B2D/routers/RTR_A1B2C3D4" \
  -H "Authorization: Bearer <session_token>"

Path Parameters

empresa_id

string

required

Company ID.

router_id

string

required

Router ID to retrieve.

Response

Returns a single RouterResponse object. Returns HTTP 404 if the router does not exist or belongs to a different company.

PUT /admin/empresas//routers//toggle-activo

Toggles the active/inactive state of a router. Inactive routers cannot process payments or be used to create hotspot users.

cURL

curl -X PUT "https://api.example.com/admin/empresas/EMP_3A9F1C0B2D/routers/RTR_A1B2C3D4/toggle-activo" \
  -H "Authorization: Bearer <session_token>"

Path Parameters

empresa_id

string

required

Company ID.

router_id

string

required

Router ID to toggle.

Response

Router Activated

{
  "message": "Router activado correctamente",
  "router_id": "RTR_A1B2C3D4",
  "activo": true
}

Router Deactivated

{
  "message": "Router desactivado correctamente",
  "router_id": "RTR_A1B2C3D4",
  "activo": false
}

POST /admin/empresas//routers//regenerate-api-key

Revokes the current API Key and issues a new one. Use this when a client loses or compromises their API Key. The previous key stops working immediately.

The new new_api_key value is shown only in this response. It cannot be retrieved again. If you lose it, you must regenerate again.

cURL

curl -X POST "https://api.example.com/admin/empresas/EMP_3A9F1C0B2D/routers/RTR_A1B2C3D4/regenerate-api-key" \
  -H "Authorization: Bearer <session_token>"

Path Parameters

empresa_id

string

required

Company ID.

router_id

string

required

Router ID whose key should be rotated. The router must be active (activo = true).

Response

message

string

required

Always "API Key regenerada exitosamente" on success.

router_id

string

required

The router whose key was regenerated.

new_api_key

string

required

The new full API Key including the jwt_ prefix. Shown only once.

api_key_info

object

required

Show api_key_info fields

key_id

string

New key identifier.

issued_at

string (ISO 8601)

When the new key was issued.

expires_at

string (ISO 8601)

When the new key expires.

type

string

Always "router_api_key".

previous_key_revoked

boolean

required

true if a previous active key was found and revoked. false if there was no active key to revoke.

Example Response

{
  "message": "API Key regenerada exitosamente",
  "router_id": "RTR_A1B2C3D4",
  "new_api_key": "jwt_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJrZXlfbmV3a2V5aWQxMjM0NTYifQ.new_signature",
  "api_key_info": {
    "key_id": "key_newkeyid123456",
    "issued_at": "2025-01-15T15:00:00",
    "expires_at": "2026-01-15T15:00:00",
    "type": "router_api_key"
  },
  "previous_key_revoked": true
}

Error Responses

Status	Detail
`400`	`"No se puede regenerar API key de un router inactivo"`
`404`	Router not found or does not belong to the company

GET /admin/empresas//routers//api-keys

Returns the complete history of all API Keys (active and revoked) for a router, ordered by issuance date descending. Useful for auditing key rotations and detecting suspicious activity.

cURL

curl -X GET "https://api.example.com/admin/empresas/EMP_3A9F1C0B2D/routers/RTR_A1B2C3D4/api-keys" \
  -H "Authorization: Bearer <session_token>"

Path Parameters

empresa_id

string

required

Company ID.

router_id

string

required

Router ID to fetch key history for.

Response

Returns an array of RouterAPIKeyInfo objects.

key_id

string

required

Unique key identifier, e.g. "key_a1b2c3d4e5f6g7h8".

router_id

string

required

Router this key was issued for.

empresa_id

string

required

Company this key belongs to.

issued_at

string (ISO 8601)

required

When the key was generated.

expires_at

string (ISO 8601)

required

When the key expires or expired.

revoked

boolean

required

true if the key has been manually revoked.

revoked_at

string (ISO 8601)

Timestamp of revocation. null if never revoked.

last_used

string (ISO 8601)

Timestamp of the most recent successful API call made with this key. null if the key has never been used.

use_count

integer

Total number of successful authenticated requests made with this key. Defaults to 0.

Example Response

[
  {
    "key_id": "key_newkeyid123456",
    "router_id": "RTR_A1B2C3D4",
    "empresa_id": "EMP_3A9F1C0B2D",
    "issued_at": "2025-01-15T15:00:00",
    "expires_at": "2026-01-15T15:00:00",
    "revoked": false,
    "revoked_at": null,
    "last_used": "2025-01-15T16:30:00",
    "use_count": 5
  },
  {
    "key_id": "key_a1b2c3d4e5f6g7h8",
    "router_id": "RTR_A1B2C3D4",
    "empresa_id": "EMP_3A9F1C0B2D",
    "issued_at": "2025-01-10T09:00:00",
    "expires_at": "2026-01-10T09:00:00",
    "revoked": true,
    "revoked_at": "2025-01-15T15:00:00",
    "last_used": "2025-01-15T14:55:00",
    "use_count": 87
  }
]

POST /admin/empresas//routers//api-keys//revoke

Revokes a specific API Key by its key_id without issuing a new one. Use this when a key is suspected to have been compromised and you need to block it before generating a replacement via regenerate-api-key.

cURL

curl -X POST "https://api.example.com/admin/empresas/EMP_3A9F1C0B2D/routers/RTR_A1B2C3D4/api-keys/key_a1b2c3d4e5f6g7h8/revoke" \
  -H "Authorization: Bearer <session_token>"

Path Parameters

empresa_id

string

required

Company ID.

router_id

string

required

Router ID.

key_id

string

required

Key ID to revoke, e.g. "key_a1b2c3d4e5f6g7h8". Obtain from the GET api-keys endpoint.

Response

{
  "message": "API Key revocada exitosamente",
  "key_id": "key_a1b2c3d4e5f6g7h8",
  "router_id": "RTR_A1B2C3D4",
  "revoked_at": "2025-01-15T16:00:00.123456"
}

Error Responses

Status	Detail
`400`	`"La API Key ya está revocada"`
`404`	API Key not found for this router/company

GET /admin/empresas//routers//api-key-status

Returns the status of the currently active API Key for a router, including expiry information and usage warnings. Use this for health monitoring dashboards.

cURL

curl -X GET "https://api.example.com/admin/empresas/EMP_3A9F1C0B2D/routers/RTR_A1B2C3D4/api-key-status" \
  -H "Authorization: Bearer <session_token>"

Path Parameters

empresa_id

string

required

Company ID.

router_id

string

required

Router ID to check.

Response

router_id

string

required

The router ID checked.

has_active_key

boolean

required

true if there is a non-revoked, non-expired key. false otherwise.

key_id

string

Active key identifier. null if no active key exists.

issued_at

string (ISO 8601)

When the active key was issued.

expires_at

string (ISO 8601)

When the active key expires.

expires_in_days

integer

Remaining days until expiry. A warning is set when this value is below 30.

last_used

string (ISO 8601)

Last time the key was used successfully.

use_count

integer

Total authenticated requests made with the active key.

status

string

"active" if a valid key exists, "no_key" if none found.

warning

string

Advisory message, e.g. "La API Key expira en 15 días" or "Esta API Key nunca ha sido usada". null if no warnings.

recommendation

string

Suggested action, e.g. "Considerar regenerar la API Key pronto". null if no recommendation.

message

string

Set to "No hay API Key activa para este router" when has_active_key is false.

Active Key — No Warnings

{
  "router_id": "RTR_A1B2C3D4",
  "has_active_key": true,
  "key_id": "key_newkeyid123456",
  "issued_at": "2025-01-15T15:00:00",
  "expires_at": "2026-01-15T15:00:00",
  "expires_in_days": 364,
  "last_used": "2025-01-15T16:30:00",
  "use_count": 42,
  "status": "active",
  "warning": null,
  "recommendation": null,
  "message": null
}

Active Key — Expiring Soon

{
  "router_id": "RTR_A1B2C3D4",
  "has_active_key": true,
  "key_id": "key_oldkeyid999888",
  "issued_at": "2024-01-20T10:00:00",
  "expires_at": "2025-01-30T10:00:00",
  "expires_in_days": 15,
  "last_used": "2025-01-15T08:00:00",
  "use_count": 1240,
  "status": "active",
  "warning": "La API Key expira en 15 días",
  "recommendation": "Considerar regenerar la API Key pronto",
  "message": null
}

No Active Key

{
  "router_id": "RTR_A1B2C3D4",
  "has_active_key": false,
  "key_id": null,
  "issued_at": null,
  "expires_at": null,
  "expires_in_days": null,
  "last_used": null,
  "use_count": 0,
  "status": "no_key",
  "warning": null,
  "recommendation": "Generar una nueva API Key",
  "message": "No hay API Key activa para este router"
}

DELETE /admin/empresas//routers/

Permanently deletes a router and all its associated API Key tracking records. This action is irreversible.

Deletion fails with HTTP 400 if the router has any products associated with it. You must delete or reassign all products before deleting the router. Transactions referencing this router remain in the database.

cURL

curl -X DELETE "https://api.example.com/admin/empresas/EMP_3A9F1C0B2D/routers/RTR_A1B2C3D4" \
  -H "Authorization: Bearer <session_token>"

Path Parameters

empresa_id

string

required

Company ID.

router_id

string

required

Router ID to delete permanently.

Response

{
  "message": "Router eliminado exitosamente",
  "router_id": "RTR_A1B2C3D4",
  "empresa_id": "EMP_3A9F1C0B2D"
}

Error Responses

Status	Detail
`400`	`"No se puede eliminar el router porque tiene N producto(s) asociado(s)"`
`404`	Router not found or does not belong to the company

Public Endpoints

Admin Endpoints

Super Admin Endpoints

Webhooks

Super Admin: Router and API Key Management Endpoints

POST /admin/empresas//routers

Path Parameters

Request Body

Response

GET /admin/empresas//routers

Path Parameters

Response

GET /admin/empresas//routers/

Path Parameters

Response

PUT /admin/empresas//routers//toggle-activo

Path Parameters

Response

POST /admin/empresas//routers//regenerate-api-key

Path Parameters

Response

Error Responses

GET /admin/empresas//routers//api-keys

Path Parameters

Response

POST /admin/empresas//routers//api-keys//revoke

Path Parameters

Response

Error Responses

GET /admin/empresas//routers//api-key-status

Path Parameters

Response

DELETE /admin/empresas//routers/

Path Parameters

Response

Error Responses

Build docs developers (and LLMs) love

Public Endpoints

Admin Endpoints

Super Admin Endpoints

Webhooks

Documentation Index

​POST /admin/empresas//routers

​Path Parameters

​Request Body

​Response

​GET /admin/empresas//routers

​Path Parameters

​Response

​GET /admin/empresas//routers/

​Path Parameters

​Response

​PUT /admin/empresas//routers//toggle-activo

​Path Parameters

​Response

​POST /admin/empresas//routers//regenerate-api-key

​Path Parameters

​Response

​Error Responses

​GET /admin/empresas//routers//api-keys

​Path Parameters

​Response

​POST /admin/empresas//routers//api-keys//revoke

​Path Parameters

​Response

​Error Responses

​GET /admin/empresas//routers//api-key-status

​Path Parameters

​Response

​DELETE /admin/empresas//routers/

​Path Parameters

​Response

​Error Responses

Build docs developers (and LLMs) love

POST /admin/empresas//routers

Path Parameters

Request Body

Response

GET /admin/empresas//routers

Path Parameters

Response

GET /admin/empresas//routers/

Path Parameters

Response

PUT /admin/empresas//routers//toggle-activo

Path Parameters

Response

POST /admin/empresas//routers//regenerate-api-key

Path Parameters

Response

Error Responses

GET /admin/empresas//routers//api-keys

Path Parameters

Response

POST /admin/empresas//routers//api-keys//revoke

Path Parameters

Response

Error Responses

GET /admin/empresas//routers//api-key-status

Path Parameters

Response

DELETE /admin/empresas//routers/

Path Parameters

Response

Error Responses