Rotar API Key

POST /api/v1/contribuyentes/:contribuyenteId/api-keys/:id/rotar — generá un nuevo secreto y revocá el anterior.

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

Genera una nueva clave en texto plano para un API key existente. La clave anterior queda inmediatamente revocada.

Autenticación

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

Path parameters

Parámetro	Tipo	Descripción
`contribuyenteId`	`integer`	ID interno del contribuyente
`id`	`integer`	`apiKeyId` de la clave a rotar

Request body

Sin cuerpo. La operación se invoca solo con el POST.

Respuesta exitosa

Status: 200 OK

{
  "status": "success",
  "payload": {
    "apiKeyId": 42,
    "nombre": "Integración ERP Producción",
    "key": "sk_live_2d6f8a1c4b9e7d3f0a5c8b6e9d1f4a7c",
    "keyPrefix": "sk_live_2d6f8a1c",
    "estaActivo": true,
    "ultimoUso": null,
    "expiraEn": "2027-01-01T00:00:00",
    "fechaCreacion": "2026-01-15T11:00:00"
  }
}

La rotación invalida la clave anterior al instante. Cualquier integración que siga usando la clave vieja recibirá 401 Unauthorized en el siguiente request.

El nuevo valor key se muestra una única vez. Guardalo inmediatamente — no se puede recuperar después.

Patrón recomendado (sin downtime)

Llamá al endpoint de rotación y guardá la nueva key en tu vault de secretos.

Actualizá la configuración de tu integración con la nueva clave.

Reiniciá o recargá el servicio para que tome la nueva variable.

Verificá que los nuevos requests responden 200.

Si tu integración corre en múltiples instancias, hacé el rollout gradual: la clave nueva ya está activa, pero la vieja deja de funcionar. Coordiná la actualización antes de invocar rotar.

Errores

Status	Tipo	Descripción
401	—	JWT inválido, expirado o ausente
403	`access-denied`	El usuario no es propietario del contribuyente
404	`api-key-not-found`	El `apiKeyId` no existe o no pertenece al contribuyente

Ejemplo

curl -X POST \
  https://api.sifende.com.py/api/v1/contribuyentes/42/api-keys/42/rotar \
  -H "Authorization: Bearer $JWT"

On this page