La autenticación de KSeF 2.0 consta de dos capas: primero se acredita una identidad mediante una firma XAdES o un token KSeF heredado; después, se utiliza el token de acceso JWT recibido para llamar a los endpoints protegidos de la API. Según las normas vigentes el 28 de agosto de 2026, el método con token dejará de estar disponible el 31 de diciembre de 2026. Las nuevas integraciones en producción deberían utilizar certificados KSeF de tipo 1.

Esta guía se contrastó con la documentación del Ministerio de Finanzas y el repositorio oficial de la API de KSeF el 28 de agosto de 2026. La API sigue evolucionando, así que considera el [registro oficial de cambios](https://github.com/CIRFMF/ksef-api/blob/main/api-changelog.md) parte de las dependencias de producción.

## ¿Cómo funciona la autenticación de KSeF 2.0?

KSeF 2.0 separa la autenticación de las sesiones de facturación. Primero se establece quién realiza la llamada y en qué contexto del contribuyente. Solo después de recibir un `accessToken` se puede abrir una sesión en línea o por lotes, enviar facturas, consultar metadatos o recuperar documentos UPO.

En este flujo aparecen cuatro credenciales. Confundirlas provoca la mayoría de los errores de implementación:

| Credencial | Qué acredita | Duración habitual | Dónde se utiliza |
|---|---|---|---|
| **Certificado KSeF o certificado cualificado** | La identidad de la persona o entidad que se autentica | Certificado KSeF: hasta dos años | Firma la solicitud de autenticación XAdES |
| **Token KSeF** | Un secreto heredado vinculado a un contexto y a un subconjunto inmutable de permisos | Hasta que se revoque; la legislación vigente permite este método hasta el 31 de diciembre de 2026 | Inicia el flujo alternativo de autenticación mediante token |
| **`authenticationToken`** | Una operación de autenticación pendiente | Temporal y destinado a un único fin | Consulta el estado y se canjea una sola vez |
| **`accessToken` y `refreshToken`** | La sesión actual autenticada en la API | Acceso: minutos, según `exp`; renovación: hasta siete días | Autoriza las llamadas a la API y renueva el acceso |

La [guía oficial de autenticación](https://github.com/CIRFMF/ksef-api/blob/main/uwierzytelnianie.md) describe los dos últimos como JWT emitidos tras completar correctamente una operación asíncrona. El token de acceso se envía en `Authorization: Bearer ...`. No es el mismo objeto que el antiguo token KSeF de larga duración.

### El contexto y la identidad son conceptos distintos

Cada inicio de sesión combina dos preguntas:

1. **¿En qué contexto operará esta sesión?** Normalmente, el de una empresa identificada mediante su NIP, aunque KSeF también admite otros identificadores de contexto.
2. **¿Qué identidad se está autenticando?** Puede ser la empresa, una persona identificada mediante PESEL o NIP, o una identidad vinculada a la huella digital de un certificado.

KSeF comprueba si el sujeto que se autentica tiene al menos un permiso activo en el contexto seleccionado. Poseer un certificado válido no basta por sí solo. Esta separación cobra importancia cuando un proveedor contable o un empleado trabaja para varias empresas: un mismo certificado de identidad puede servir en varios contextos, mientras que los permisos varían en cada uno.

## ¿Qué método de autenticación de KSeF deberías elegir en 2026?

Para una nueva integración en producción, utiliza **XAdES con un certificado de autenticación KSeF de tipo 1**. Conserva la compatibilidad con los tokens KSeF heredados solo como puente durante la migración. El [reglamento actualmente vigente](https://dziennikustaw.gov.pl/DU/2025/1815) permite ese método hasta el 31 de diciembre de 2026, y las directrices actuales del Ministerio indican que, a partir del 1 de enero de 2027, se mantendrán los certificados.

Conviene matizar ese plazo. En junio de 2026, el Ministerio [propuso ampliar la vigencia de los tokens KSeF](https://ksef.podatki.gov.pl/wyjasnienia/pierwsze-konsultacje-po-czesciowym-wdrozeniu-ksef-podsumowanie/) con periodos de validez más cortos y controles de renovación. A la fecha de verificación de este artículo, se trata de una propuesta sometida a consulta, no de una norma promulgada. Hasta que cambie el reglamento, planifica la migración conforme al plazo vinculante.

| Decisión | Certificado KSeF de tipo 1 | Token KSeF heredado |
|---|---|---|
| Nueva integración en producción | **Recomendado** | No crees una nueva dependencia de este método |
| Funciona en varios contextos autorizados | Sí | No; cada token pertenece a un único contexto |
| Contiene los permisos | No; KSeF comprueba los permisos actuales en el servidor | Contiene un subconjunto fijo elegido al crearlo |
| Modelo de rotación | Certificado con caducidad, válido durante un máximo de dos años | El secreto sigue vigente hasta que se revoca, aunque la legislación actual fija el fin del método en 2026 |
| Inicio de sesión criptográfico | Firma XAdES | Cifra `{tokenKSeF}\|{timestampMs}` con la clave pública de KSeF |
| Principal riesgo operativo | Filtración de la clave privada o caducidad | Filtración del secreto, proliferación de permisos y migración forzosa |

La distinción procede directamente del [manual de KSeF 2.0 del Ministerio de Finanzas](https://ksef.podatki.gov.pl/media/jzrevse3/podrecznik-ksef-20-cz-i-rozpoczecie-korzystania-z-ksef-20260209.pdf): un certificado contiene la identidad, pero no permisos de KSeF; un token KSeF, en cambio, contiene un subconjunto de permisos y se limita a un único contexto.

### No utilices un certificado offline para autenticarte

KSeF emite dos tipos de certificado con fines distintos:

- `Authentication` firma la solicitud de inicio de sesión.
- `Offline` acredita la autenticidad del emisor y la integridad de la factura en un flujo offline.

Un certificado `Offline` no sirve para autenticar llamadas a la API. La [guía oficial de certificados](https://github.com/CIRFMF/ksef-api/blob/main/certyfikaty-KSeF.md) también desaconseja utilizar un certificado de autenticación para firmar las pruebas de una factura offline. Guarda y etiqueta las dos claves privadas por separado para impedir que un despliegue seleccione la incorrecta.

## ¿Cómo se implementa la autenticación mediante certificado?

La autenticación mediante certificado sigue un flujo asíncrono de reto y respuesta. El cliente firma el XML en local, lo envía, consulta el estado de la operación y canjea un token temporal exactamente una vez.

### 1. Solicita un reto

Llama a `POST /auth/challenge`. Conserva tanto el valor del reto como su marca temporal. El reto es válido durante 10 minutos, vincula la siguiente solicitud a un intento de autenticación reciente e impide reutilizar un documento firmado antiguo. Genera un reto nuevo para cada intento en lugar de almacenarlo en caché.

### 2. Crea `AuthTokenRequest`

Construye la solicitud XML con:

- el reto;
- el identificador y el valor del contexto;
- el tipo de identificador del sujeto;
- una `AuthorizationPolicy` opcional que limite las direcciones, los rangos o las máscaras IPv4 permitidos.

Si el certificado contiene el NIP de la empresa, el sujeto puede autenticarse directamente. Si una persona firma en nombre de una empresa, KSeF obtiene del certificado el identificador de esa persona y comprueba sus permisos en el contexto de la empresa. Los certificados cualificados que no incluyan NIP ni PESEL pueden requerir una huella digital de certificado autorizada.

### 3. Genera una firma XAdES válida

Firma el XML con el certificado de identidad seleccionado y su clave privada. No des por hecho que KSeF 2.0 seguirá aceptando una muestra XAdES antigua de KSeF 1.0. La versión 2.1.0 de la API endureció la validación XAdES y, según el [registro de cambios de la API de KSeF](https://github.com/CIRFMF/ksef-api/blob/main/api-changelog.md), las reglas actuales ya se aplican en los entornos activos. Los [requisitos XAdES vigentes](https://github.com/CIRFMF/ksef-api/blob/main/auth/podpis-xades.md) admiten firmas enveloped y enveloping, pero rechazan las detached; también establecen tamaños mínimos para las claves RSA y EC.

El Ministerio mantiene clientes de referencia para [C#](https://github.com/CIRFMF/ksef-client-csharp) y [Java](https://github.com/CIRFMF/ksef-client-java). Aunque tu aplicación utilice otro lenguaje, sus pruebas constituyen ejemplos ejecutables útiles para la serialización del XML, los identificadores de los certificados y la creación de firmas.

### 4. Envía la solicitud y consulta su estado

Envía el XML firmado a `POST /auth/xades-signature`. Una respuesta correcta contiene:

- `referenceNumber`, que identifica la operación asíncrona;
- `authenticationToken`, un JWT temporal que solo sirve para esta operación.

Consulta `GET /auth/{referenceNumber}` con el token temporal. Acota el intervalo de consulta y clasifica las respuestas en tres grupos: operación aún en curso, éxito definitivo y error definitivo. Las firmas no válidas, los problemas con el certificado, la falta de permisos y los bloqueos de seguridad no son errores transitorios de red. Reintentar indefinidamente el mismo documento defectuoso solo oculta el fallo real.

### 5. Canjea el token una sola vez

Cuando la autenticación concluya correctamente, llama a `POST /auth/token/redeem` con el token temporal. KSeF devuelve `accessToken` y `refreshToken`. El canje solo puede hacerse una vez; la [documentación de autenticación](https://github.com/CIRFMF/ksef-api/blob/main/uwierzytelnianie.md) indica que reutilizar el mismo `authenticationToken` devuelve un HTTP 400.

Este es un esquema compacto de la implementación:

```text
challenge = POST /auth/challenge
request = build_auth_xml(challenge, context, subject, allowed_ips)
signed_xml = xades_sign(request, identity_certificate, private_key)

operation = POST /auth/xades-signature(signed_xml)
status = poll GET /auth/{operation.referenceNumber}
  Authorization: Bearer {operation.authenticationToken}

tokens = POST /auth/token/redeem
  Authorization: Bearer {operation.authenticationToken}

call protected endpoints with tokens.accessToken
refresh before accessToken.exp with tokens.refreshToken
```

### 6. Abre las sesiones de facturación por separado

Autenticarse no abre una sesión de facturación. Una vez que dispongas de un token de acceso válido, utilízalo para abrir `POST /sessions/online` o `POST /sessions/batch`. KSeF 2.0 separa estos conceptos de forma deliberada, de modo que una sesión autenticada puede autorizar más operaciones que la apertura de una única sesión propia de las integraciones anteriores.

### ¿Qué ocurre si aún te autenticas con un token KSeF?

La rama heredada parte también de `POST /auth/challenge`, pero no firma un XML. Forma `{tokenKSeF}|{timestampMs}` con el secreto y la marca temporal del reto, cífralo con la clave pública actual de KSeF mediante RSA-OAEP con SHA-256/MGF1 y envía el resultado en Base64 a `POST /auth/ksef-token` junto con el reto, el contexto y el `publicKeyId` seleccionado.

Obtén las claves de cifrado mediante `GET /security/public-key-certificates`; no fijes una única clave pública en el código. La [guía oficial de rotación de claves](https://github.com/CIRFMF/ksef-api/blob/main/bezpieczenstwo/klucze-publiczne-do-szyfrowania.md) describe tanto la rotación planificada como la de emergencia. Si KSeF rechaza un identificador de clave retirado o desconocido, actualiza el conjunto de claves y repite la operación con un reto nuevo.

A partir de ahí, la consulta de estado y el canje único coinciden con el flujo XAdES. El token KSeF nunca debe aparecer en los registros. Es el secreto raíz de esta rama, no el `authenticationToken` temporal ni el JWT de acceso que se devuelve.

## ¿Cómo se deben gestionar los tokens de acceso y renovación?

Trata ambos JWT recibidos como credenciales, no como metadatos de sesión inofensivos. Aunque el token de acceso dura poco, se puede utilizar hasta la hora indicada en `exp`, incluso si un administrador modifica los permisos del sujeto durante ese intervalo. Los tokens de acceso que se emitan tras una renovación incorporarán las funciones y los permisos vigentes.

Incorpora al cliente los siguientes controles:

1. **Lee `exp`; no codifiques una duración estimada.** Renueva el token con un margen de seguridad y una variación aleatoria para que no todos los workers lo hagan en el mismo segundo.
2. **Una sola renovación simultánea por conjunto de credenciales.** Cuando varios workers detecten la caducidad, deja que uno renueve el token y comparta el resultado. Las avalanchas de renovaciones paralelas añaden modos de fallo sin mejorar la disponibilidad.
3. **Nunca registres tokens bearer.** Oculta las cabeceras `Authorization`, los cuerpos de las respuestas de los endpoints de tokens, los payloads de las excepciones y los atributos de las trazas.
4. **No guardes los tokens de renovación en el almacenamiento del navegador.** Una integración de servidor debería conservarlos en un almacén cifrado de credenciales cuyo acceso se limite al worker que los necesite.
5. **Si falla la renovación, vuelve a autenticarte.** Ante un token de renovación caducado o no válido, el cliente debe regresar al flujo con certificado, no entrar en un bucle de renovaciones sin límite.
6. **Usa con cuidado la hora del servidor.** Una desviación del reloj cerca de `exp` provoca fallos intermitentes de autorización. Supervisa la sincronización horaria y renueva el token con antelación.

La guía oficial describe la duración del token de acceso como varios minutos y la validez del token de renovación como un máximo de siete días. Son límites de implementación, no un motivo para copiar una constante numérica de un artículo del blog. El JWT y el contrato vigente de la API son la fuente canónica.

## ¿Cómo interactúan los permisos con los certificados KSeF?

Un certificado KSeF acredita una identidad; no es una llave maestra. La [documentación de certificados](https://github.com/CIRFMF/ksef-api/blob/main/certyfikaty-KSeF.md) indica que el certificado no se asigna a ningún contexto ni contiene permisos de KSeF. KSeF evalúa en el servidor los permisos del sujeto para el contexto solicitado.

Esto permite un modelo de acceso más limpio:

- emitir un certificado de identidad a la persona o entidad que opera la integración;
- conceder solo los permisos necesarios en cada contexto del contribuyente;
- consultar los permisos efectivos durante la configuración y el diagnóstico;
- retirar los permisos cuando finalice la relación, sin revocar innecesariamente el certificado de identidad en todos los contextos;
- revocar el certificado si la clave privada se ve comprometida o si ya no se debe confiar en la propia credencial de identidad.

Para un worker que solo envía facturas, empieza con `InvoiceWrite`. Añade `InvoiceRead` únicamente si ese proceso descarga o busca facturas. Mantén `CredentialsManage` fuera de los workers que procesan facturas de forma rutinaria. La [guía oficial de permisos](https://github.com/CIRFMF/ksef-api/blob/main/uprawnienia.md) ofrece consultas sobre los permisos y las funciones vigentes, más seguras que deducir el acceso de un inicio de sesión correcto realizado meses atrás.

Hay un aspecto que merece especial atención: la solicitud de autenticación XAdES no contiene un campo `requestedPermissions` que convierta una identidad con permisos amplios en una sesión de certificado con alcance limitado. Si se autentica una identidad Owner, el acceso resultante puede reflejar los derechos actuales de esa identidad. Por tanto, el mínimo privilegio empieza por la persona o entidad y las concesiones que tenga en el servidor, no por el archivo del certificado. La política de IP opcional restringe desde dónde se puede usar un token, no qué operaciones puede realizar.

### La revocación no es instantánea para todas las credenciales

Hay que tener en cuenta dos efectos temporales:

- Según el manual del Ministerio, revocar un certificado KSeF de tipo 1 utilizado por una sesión activa pone fin a esa sesión.
- Eliminar un permiso no reescribe retroactivamente un token de acceso ya emitido. El token puede seguir siendo válido hasta `exp`; al renovarlo, se obtienen los permisos actuales.

Para contener un incidente urgente, revoca el certificado comprometido y detén el worker local. En una baja ordinaria, elimina los permisos, invalida en tu sistema el material de renovación almacenado y asume un breve periodo residual durante el que el token de acceso seguirá vigente. Registra el sujeto, el contexto, la hora de emisión del token y el número de serie del certificado, pero nunca el valor del token ni la clave privada.

## ¿Qué cambia entre TEST, DEMO y producción?

El código de autenticación debería ser idéntico en todos los entornos, pero las premisas de confianza no lo son.

| Entorno | Endpoint | Qué verificar |
|---|---|---|
| TEST | `https://api-test.ksef.mf.gov.pl/v2` | Comportamiento actual de la API, validación XAdES, gestión de errores y lógica de rotación |
| DEMO | `https://api-demo.ksef.mf.gov.pl/v2` | Cadena de certificados similar a la de producción y configuración integral |
| PRD | `https://api.ksef.mf.gov.pl/v2` | Identidad real, permisos reales, credenciales supervisadas y facturas con efectos jurídicos |

TEST acepta certificados autofirmados. Esa facilidad cambia el límite de los datos: la [guía oficial de entornos](https://github.com/CIRFMF/ksef-api/blob/main/srodowiska.md) advierte de que varios integradores pueden autenticarse en el mismo contexto de empresa de pruebas. Utiliza NIP aleatorios y datos de factura sintéticos. Nunca envíes a TEST la identidad, la dirección o una factura reales de un cliente, ni credenciales de producción.

No promociones a DEMO ni a producción un certificado autofirmado que solo hayas probado en TEST. Valida en DEMO la ruta real del certificado, incluida la validación de la cadena, los datos de la CSR, la carga de secretos, las alertas de caducidad del certificado y una rotación con las credenciales antiguas y las nuevas solapadas.

## ¿Qué deberías migrar antes del plazo actual de 2027?

Si tu integración aún se inicia con un token KSeF, completa la autenticación mediante certificado antes de que termine 2026, conforme a las normas actualmente vigentes. Una posible prórroga puede cambiar la fecha, pero no debería alterar la arquitectura de una nueva integración. La secuencia más segura es operativa, no solo criptográfica.

1. Haz inventario de todos los tokens KSeF, sus propietarios, contextos, permisos, últimos usos y servicios que los consumen.
2. Emite certificados KSeF de tipo 1 para las personas o entidades correspondientes.
3. Implementa en TEST el reto XAdES, la consulta de estado, el canje y la renovación.
4. Ejecuta el flujo con certificado en DEMO utilizando un almacenamiento de claves y una política de red similares a los de producción.
5. Activa la autenticación mediante certificado en producción con un despliegue controlado.
6. Compara los contextos válidos y los permisos efectivos de las rutas antigua y nueva.
7. Migra todo el tráfico, observa al menos un ciclo completo de rotación y recuperación ante fallos y, después, revoca los tokens KSeF antiguos.

No esperes hasta diciembre para descubrir que el proceso depende de un sello cualificado en manos de una sola persona, que los datos de identidad de la CSR no coinciden o que tu HSM no puede generar la firma XAdES necesaria. La emisión de certificados es asíncrona, estos caducan y corregir la responsabilidad operativa lleva más tiempo que modificar el código de un endpoint.

## Cómo aborda Kit la autenticación de KSeF

La integración [KSeF for Stripe](https://ksef.startupkit.app/) de Kit convierte las facturas definitivas de Stripe al formato FA(3), las envía a KSeF y conserva las pruebas resultantes dentro del flujo de facturación. Esa experiencia confirma la arquitectura de esta guía: las credenciales de identidad, el contexto del contribuyente, los permisos, el acceso de corta duración a la API, las sesiones de facturación y la recuperación de UPO son estados distintos y deberían seguir separados en el código.

El criterio práctico es sencillo: utiliza certificados para la identidad, permisos para la autorización, JWT para un acceso limitado a la API y registros explícitos para cada operación asíncrona. Sigue el enfoque general de [seguridad de Kit](/security), supervisa el [registro de cambios de KSeF](https://github.com/CIRFMF/ksef-api/blob/main/api-changelog.md), prueba la rotación antes de la caducidad y convierte el actual plazo de 2027 para los tokens en un hito de migración, no en un incidente de Año Nuevo.

> [!CTA]
> **¿Gestionas la facturación de Stripe para una empresa polaca?** Descubre cómo [KSeF for Stripe](https://ksef.startupkit.app/) se ocupa del envío de FA(3) y la recuperación de UPO, consulta la [documentación general de Kit](/docs) o [empieza tu prueba gratuita](/users/sign_up).