Autenticación de la API y tokens Bearer

Cómo funciona la autenticación

1. Regístrese e inicie sesión en su cuenta de Quote3D.
2. Genere un token de API desde su panel de control en la pestaña "Tokens".
3. Incluya el token en sus solicitudes a la API. Se admiten Authorization: Bearer y X-API-Token:
   Authorization: Bearer YOUR_TOKEN_HERE
4. El servidor verifica su token y concede acceso si es válido y no ha expirado.

Ámbitos de los tokens

El ámbito de un token determina a qué endpoints puede acceder. Usted elige el ámbito al crear el token, y puede verlo en la página de Tokens de su panel de control.

• Acceso total — el valor predeterminado para un token del lado del servidor. Accede a todos los endpoints que su plan permite.
• Widget — el ámbito que debe utilizarse para un token que se incrusta en una tienda virtual. Está limitado a lo que el widget incrustable necesita y no puede acceder a webhooks, detalles de la cuenta, analíticas, uso o cuota.

Una llamada a un endpoint fuera del ámbito del token es rechazada con un error 403, aunque el token en sí sea válido. Si una solicitud falla con un error 403 mientras que el mismo token funciona en otros lugares, compruebe su ámbito antes que cualquier otra cosa.

Ciclo de vida del token

• El valor de un token se muestra una sola vez, al momento de su creación. No se puede recuperar después; guárdelo inmediatamente en su gestor de secretos. Si lo pierde, rote el token para obtener un nuevo valor.
• Los tokens pueden crearse con una fecha de expiración. Un token expirado deja de funcionar y devuelve un error 401; el panel de control muestra la fecha de expiración de cada token.
• Al rotar un token, se genera un nuevo valor y el anterior queda invalidado de inmediato. Implemente el nuevo valor antes de realizar la rotación, ya que las solicitudes en curso que utilicen el token antiguo comenzarán a fallar inmediatamente.
• Un token puede restringirse a una lista de direcciones IP. Las llamadas desde cualquier otra dirección son rechazadas con un error 403, algo que suele ocurrir tras mover un servidor o cambiar una puerta de enlace NAT.
• Su plan limita la cantidad de tokens que puede tener. Los planes gratuitos permiten un token de servidor y un token de widget.

Cuando falla la autenticación

Una solicitud rechazada devuelve la estructura de error estándar con success: false y un mensaje corto. Ramifique según el código de estado HTTP en lugar del texto del mensaje, que puede ser modificado.

{
  "success": false,
  "error": "API token has expired"
}

• 401 — falta el token, está mal formado, ha expirado o ha sido revocado. Compruebe el nombre del encabezado y que el valor no se haya truncado al copiarlo.
• 403 — el token es válido pero no está permitido para esta llamada. Las causas habituales son una restricción de alcance o una lista de permitidos de IP que no incluye al solicitante.

Formato del Token

Los tokens de Quote3D son credenciales de API de tipo 'bearer'. Los clientes deben tratarlos como secretos opacos y evitar depender de la estructura interna del token.

Un JWT consta de tres partes:

1. Encabezado: Especifica el algoritmo de firma y el tipo de token.
2. Carga útil: Contiene datos del usuario y afirmaciones (como ID de usuario, correo electrónico y tiempo de expiración).
3. Firma: Verifica que el token no haya sido manipulado.

Un JWT se ve así:

Para las integraciones, la regla importante es simple: almacena el token de forma segura, envíalo en cada solicitud y evita analizarlo o exponerlo en el código del cliente a menos que la integración requiera explícitamente un token del lado del cliente.

Ejemplo: Usando Su Token

Aquí le mostramos cómo podría usar su token con curl:

O en el patio de juegos de la API, pegue su token en el modal de autorización (icono de candado) para autenticar su sesión. También puede usar X-API-Token en integraciones personalizadas si ese encabezado se ajusta mejor.