Skip to navigation
Empezar

Autenticación

Dos mecanismos, nunca mezclados en el mismo request:

UsoCredencialCómo se obtiene
Integración máquina-a-máquina (SDK)X-API-Key: sup_live_xxxBootstrap con X-Backend-Token (operador) o POST /companies/{id}/api-keys con JWT
Frontend humanoAuthorization: Bearer <jwt> + X-Company-ID: <uuid>POST /auth/signup o /auth/login

La key pertenece a una sola empresa y todo se filtra por ese tenant: una factura ajena responde 404 (nunca 403, para no revelar existencia). La api_key completa solo se muestra una vez, al crearla.

Máquina-a-máquina

ElementoDetalle
Formatosup_live_<prefijo>_<secreto> (o sup_test_...)
HeaderX-API-Key
Sin key o inválida/inactiva401 UNAUTHORIZED
SDKSolo usa este modo
import { Supay } from "@supay/sdk";
// Integración: solo X-API-Key, nada más
const supay = new Supay({ apiKey: "sup_live_xxx" });
// Bootstrap del operador (usa BACKEND_SECRET, no apiKey)
const op = new Supay({
  baseUrl: "http://localhost:8081",
  backendToken: process.env.BACKEND_SECRET!,
});
const { company, api_key } = await op.bootstrap.createCompany({
  nit: "123456789",
  business_name: "Mi Empresa SRL",
  ambiente: "PILOTO",
});
// api_key solo sale aquí: guárdala como secreto

Con token erróneo, el bootstrap responde 401 en texto plano (Unauthorized internal request), no el envelope JSON. Tiene rate-limit por IP.

Sesión humana (JWT + membresía)

El JWT identifica al usuario; X-Company-ID elige sobre cuál de sus empresas opera (validada en DB por request).

EndpointAuthRespuesta
POST /auth/signupninguna (rate-limit)201 + user, access_token, token_type: Bearer, expires_at
POST /auth/loginninguna200 igual; credenciales malas → 401 genérico
GET /auth/mesolo Bearerusuario
GET /auth/companiessolo Bearerempresas y rol
POST /auth/companiessolo Bearercrea empresa (quedas owner)
POST /companies/{id}/api-keysBearerkey para esa empresa
Campo signupTipoObligatorioDescripción
namestringSíNombre visible
emailstringSíÚnico, formato email
passwordstringSí8 a 72 caracteres
// Sin credenciales: el JWT se obtiene con signup/login
const auth = new Supay({ baseUrl: "http://localhost:8081" });
const session = await auth.auth.signup({
  name: "Ada",
  email: "ada@example.com",
  password: "una-clave-segura",
});
// session.access_token → úsalo como Bearer
const empresas = await auth.auth.listMyCompanies();
// Crear empresa: quedas owner, luego genera su API key
const empresa = await auth.auth.createMyCompany({
  nit: "...",
  business_name: "...",
});

Sin membresía sobre la empresa → 403. Sin X-Company-ID en rutas de negocio → 400. Ver Errores.