Saltar al contenido
NimbusNexus

Autenticación de dos factores

La autenticación de dos factores añade un segundo factor (un código TOTP de una aplicación de autenticación) además del inicio de sesión con contraseña. Los endpoints de aquí la activan, informan de su estado y la desactivan:

  • GET /api/v1/2fa/credential — genera un secreto TOTP y devuelve su código QR como imagen. El secreto en sí llega en la cabecera de respuesta X-Secret-Key.
  • POST /api/v1/2fa/totp_passcode_validation — envía ese secreto como secretKey, con un passcode actual de seis dígitos de la aplicación. Si el código coincide, la 2FA queda activada.
  • GET /api/v1/2fa/status — two_factor_enabled indica si la 2FA está activada.
  • POST /api/v1/2fa/off — desactiva la 2FA.

Cada usuario tiene un solo secreto TOTP; repetir el alta lo sustituye.

Para los usuarios del panel, la 2FA se gestiona desde el navegador, en la página de ajustes de la cuenta. A través de la API, cada llamada lee o cambia solo la 2FA propia de quien llama con una sesión iniciada, nunca la de otro usuario. Quienes llaman con una clave de API no necesitan 2FA — las claves ya son en sí un factor de "algo que tienes".

Recomendación firme: activa la 2FA en todas las cuentas de personas con roles concedidos en proyectos de producción. La mayoría de los compromisos de cuentas se deben a la reutilización de contraseñas + no tener segundo factor.

Próximos pasos

Reference

GET/api/v1/2fa/credential

Two Factor Credential

Generate a TOTP secret for the calling user and return its QR-code image; the secret is delivered in a response header.

Responses

  • 200Successful Response
  • 401Unauthorized
  • 403Forbidden
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X GET "https://api.nimbusnexus.net/api/v1/2fa/credential" \
  -H "Authorization: Bearer $NIMBUS_KEY"
POST/api/v1/2fa/off

Two Factor Off

Disable two-factor authentication for the calling user.

Responses

  • 200Successful Response
  • 401Unauthorized
  • 403Forbidden
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X POST "https://api.nimbusnexus.net/api/v1/2fa/off" \
  -H "Authorization: Bearer $NIMBUS_KEY"
GET/api/v1/2fa/status

Two Factor Status

Report whether two-factor authentication is currently enabled for the calling user.

Responses

  • 200Successful Response
  • 401Unauthorized
  • 403Forbidden
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X GET "https://api.nimbusnexus.net/api/v1/2fa/status" \
  -H "Authorization: Bearer $NIMBUS_KEY"
POST/api/v1/2fa/totp_passcode_validation

Totp Passcode Validation

Validate a TOTP passcode against the supplied secret and enable two-factor authentication on success.

Request body

FieldTypeDescription
passcode*string—
secretKey*string—

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X POST "https://api.nimbusnexus.net/api/v1/2fa/totp_passcode_validation" \
  -H "Authorization: Bearer $NIMBUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "passcode": "example",
    "secretKey": "example"
  }'

Need to make a real call? Try these endpoints in the live Swagger UI →