Portal de APIIr a StartISP

Documentación de plataforma

Integra y opera StartISP con claridad.

Esta guía describe las superficies públicas de StartISP, el flujo de identidad propio y la API inicial del plano de control.

Entorno productivo limpio

Las cuentas, empresas y suscripciones documentadas aquí pertenecen al plano de control en PostgreSQL. Los registros usados para probar el prototipo no se importan automáticamente.

Dominios del servicio

WEB
https://startisp.coSitio público del producto.
CUENTA
https://startisp.co/loginRegistro, verificación, inicio de sesión y cuenta de plataforma.
APP
https://cloud.startisp.coPanel operativo de cada ISP.
ADMIN
https://admin.startisp.coPanel maestro, restringido al rol de plataforma.
DOCS
https://docs.startisp.coGuías para operadores y desarrolladores.
API
https://api.startisp.coReferencia y estado del servicio.

Registro y verificación

Una cuenta comienza en estado pendiente. StartISP envía un enlace de un solo uso al correo indicado; el acceso se habilita únicamente cuando el enlace se valida.

  1. La persona registra nombre, correo y una contraseña robusta.
  2. El servidor responde de forma genérica para no revelar si un correo ya existe.
  3. El trabajador de correo envía el enlace usando el buzón configurado de StartISP.
  4. La verificación activa la cuenta; crear una empresa es una acción distinta.
POST /api/auth/register Content-Type: application/json { "displayName": "Nombre de la persona", "email": "persona@empresa.com", "password": "contraseña robusta" }

Sesiones y protección CSRF

Al iniciar sesión, el navegador recibe una cookie Secure, HttpOnly y de alcance exclusivo al host. El token CSRF se devuelve por JSON y se rota al consultar la sesión.

No guardes credenciales en el navegador

La contraseña nunca debe almacenarse. El frontend mantiene el token CSRF solamente en memoria y la cookie de sesión no es accesible desde JavaScript.

GET /api/auth/session # Respuesta autenticada { "authenticated": true, "csrfToken": "…", "user": { "id": "…", "email": "…", "platformAccess": true, "platformAdmin": false, "platformPermissions": ["platform.read"] } }

Endpoints de autenticación

POST
/api/auth/registerCrea una cuenta pendiente y encola la verificación.
POST
/api/auth/verify-emailConsume el token de verificación.
POST
/api/auth/loginCrea una sesión después de validar las credenciales.
GET
/api/auth/sessionDevuelve el usuario y rota el token CSRF.
POST
/api/auth/logoutRevoca la sesión. Requiere X-CSRF-Token.
POST
/api/auth/forgot-passwordEncola un correo de recuperación sin revelar cuentas.
POST
/api/auth/reset-passwordConsume el token, cambia la contraseña y revoca las sesiones previas.
POST
/api/auth/accept-invitationConsume una invitación, fija la contraseña y activa una cuenta pendiente. El token llega en el fragmento del enlace y no se envía en la URL HTTP.

Cuenta y organizaciones

Después de iniciar sesión, la cuenta puede consultar las empresas a las que pertenece, su rol y el estado de la suscripción asociada.

GET
/api/account/overviewDevuelve únicamente las organizaciones invitadas o activas del usuario autenticado.

Administración maestra

Las consultas administrativas requieren platform.read o platform.admin. Solo platform.admin permite crear o modificar registros; las mutaciones exigen, además, el encabezado CSRF.

GET
/api/admin/overviewTotales del plano de control.
GET
/api/admin/usersDirectorio paginado de cuentas.
POST
/api/admin/users/inviteCrea o reenvía una invitación para una cuenta pendiente; nunca reactiva una cuenta deshabilitada.
PATCH
/api/admin/users/{id}Actualiza nombre o estado de una cuenta.
GET
/api/admin/tenantsDirectorio paginado de empresas.
POST
/api/admin/tenantsCrea una empresa real de manera explícita.
GET
/api/admin/productsLista el catálogo comercial.
POST
/api/admin/productsCrea un producto comercial.
GET
/api/admin/pricesLista precios y modelos de cobro.
POST
/api/admin/pricesCrea un precio para un producto activo.
GET
/api/admin/membershipsLista usuarios vinculados con empresas y sus roles.
PUT
/api/admin/tenants/{tenantId}/members/{userId}Asigna o actualiza el rol de un usuario dentro de una empresa.
GET
/api/admin/subscriptionsLista asignaciones comerciales.
POST
/api/admin/subscriptionsAsigna un precio a una empresa.

Formato de errores

Las respuestas fallidas usan un código estable y un mensaje seguro para mostrar a la persona.

{ "error": { "code": "invalid_credentials", "message": "Correo o contraseña incorrectos." } }

Consulta la especificación OpenAPI 3.1 para la lista legible por herramientas.