Crear API Key

POST /api/v1/contribuyentes/:contribuyenteId/api-keys — creá un nuevo API key para autenticar llamadas de integración.

POST /api/v1/contribuyentes/:contribuyenteId/api-keys

Crea un nuevo API key para el contribuyente indicado. La clave en texto plano se devuelve una única vez en esta respuesta.

Autenticación

Authorization: Bearer {jwt} — JWT de Keycloak. El usuario autenticado debe ser propietario del contribuyente.

Path parameters

Parámetro	Tipo	Descripción
`contribuyenteId`	`integer`	ID interno del contribuyente

Request body

{
  "nombre": "Integración ERP Producción",
  "expiraEn": "2027-01-01T00:00:00"
}

Campo	Tipo	Req.	Descripción
`nombre`	`string`	Sí	Nombre descriptivo de la clave (máx. 100 caracteres)
`expiraEn`	`datetime`	No	Fecha de expiración ISO 8601. Si es `null`, la clave no expira

Respuesta exitosa

Status: 201 Created

{
  "status": "success",
  "payload": {
    "apiKeyId": 42,
    "nombre": "Integración ERP Producción",
    "key": "sk_live_8f3a9c2e7b5d4a1f6e0c9b8a7d3f2e1c",
    "keyPrefix": "sk_live_8f3a9c2e",
    "estaActivo": true,
    "ultimoUso": null,
    "expiraEn": "2027-01-01T00:00:00",
    "fechaCreacion": "2026-04-27T14:32:18"
  }
}

El campo key se muestra únicamente en esta respuesta. No se almacena en texto plano y no puede recuperarse después. Guardalo de forma segura inmediatamente — si lo perdés, vas a tener que rotar la clave.

El prefijo sk_live_ indica una clave de producción; sk_test_ corresponde al ambiente de prueba.

Errores

Status	Tipo	Descripción
401	—	JWT inválido, expirado o ausente
403	`access-denied`	El usuario no es propietario del contribuyente
404	`contribuyente-not-found`	Contribuyente no existe
422	`validation-error`	`nombre` ausente o supera los 100 caracteres

Ejemplos

curl -X POST https://api.sifende.com.py/api/v1/contribuyentes/42/api-keys \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Integración ERP Producción",
    "expiraEn": "2027-01-01T00:00:00"
  }'

const res = await fetch(
  `https://api.sifende.com.py/api/v1/contribuyentes/${contribuyenteId}/api-keys`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwt}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      nombre: 'Integración ERP Producción',
      expiraEn: '2027-01-01T00:00:00',
    }),
  }
);

const { payload } = await res.json();
// ¡Guardá payload.key inmediatamente! No se va a mostrar de nuevo.
console.log('API Key:', payload.key);