Autenticación e idempotencia

Envía Authorization: Bearer <credential> en todas las solicitudes excepto GET /pricing, GET /openapi.json y GET /openapi.yaml. Se ignoran las credenciales en parámetros de consulta u otras cabeceras.

Las credenciales usan autenticación Bearer; no se admiten credenciales vinculadas a DPoP.

• Las claves API empiezan por sk_live_. Créalas en Ajustes → Desarrollador; la clave solo se muestra una vez. Consérvala en un servidor y nunca la incluyas en una aplicación de navegador o móvil. Te enviamos un correo 7 días antes de que caduque.
• Los tokens de acceso OAuth empiezan por sf_at_. Los clientes MCP los reciben después de que los autorices; puedes desconectar un cliente en Ajustes → Desarrollador → Aplicaciones conectadas.
• Las credenciales ausentes, inválidas, caducadas o revocadas devuelven 401 UNAUTHORIZED. Una cuenta que no puede usar la API, por ejemplo porque se está eliminando, devuelve 401 ACCOUNT_UNAVAILABLE.
• Revocar una clave impide nuevas solicitudes con ella; las tareas que ya ha creado siguen ejecutándose y se pueden consultar con otras credenciales de la misma cuenta.

Una solicitud fuera del ámbito de las credenciales devuelve 403 SCOPE_DENIED. Usa una clave diferente por aplicación y entorno para poder revocar una sin afectar a las demás.

• Todas las solicitudes de creación (POST /images/*, /charts/*, /flowcharts/*) requieren una cabecera Idempotency-Key de 1 a 255 caracteres ASCII visibles. Un UUID aleatorio por solicitud es la opción más sencilla. Las subidas a POST /files también pueden enviar una; consulta archivos.
• La misma clave con el mismo cuerpo devuelve la misma tarea y nunca vuelve a reservar créditos. En las subidas para gráficos, los bytes del archivo de datos forman parte del cuerpo.
• La misma clave con un cuerpo diferente devuelve 409 IDEMPOTENCY_CONFLICT. Las solicitudes simultáneas con la misma clave nunca crean dos tareas: cada una devuelve la misma tarea o 409 IDEMPOTENCY_IN_PROGRESS con Retry-After: 1 mientras se sigue admitiendo la primera.
• Vuelve a intentarlo con la misma clave tras un tiempo de espera agotado, un error de red, un 429 o un 503: es la única forma de garantizar que no se crea una tarea dos veces.
• Cuando la tarea ya existe, un error que permite reintentar (429, 503, 409 IDEMPOTENCY_IN_PROGRESS) o 500 INTERNAL_ERROR incluye details.job_id. Reintenta con la misma clave o consulta GET /jobs/{job_id}; no uses una clave nueva, porque crearía y cobraría una segunda tarea. Una tarea aceptada que no se ha podido volver a consultar recibe 202 y estado queued.
• Una solicitud rechazada, por ejemplo 402 INSUFFICIENT_CREDITS, conserva esa respuesta para su clave. Después de recargar créditos o mejorar el plan, envíala de nuevo con una clave nueva.

• Los clientes MCP usan OAuth 2.1 con PKCE. Los tokens de acceso (sf_at_…) duran 1 hora. Un cliente que solicita el ámbito offline_access también recibe un token de renovación (sf_rt_…) válido durante 30 días y permanece conectado hasta que lo desconectes; sin offline_access, debes iniciar sesión de nuevo cuando caduque el token de acceso.
• Los tokens de renovación rotan: cada renovación devuelve uno nuevo. Presentar un token de renovación ya utilizado se considera reutilización y revoca los tokens emitidos a partir de él, por lo que el cliente debe iniciar sesión de nuevo.
• El registro dinámico de clientes acepta un cuerpo de hasta 16 KB, con límites en la longitud de cada campo y en el número de URI de redirección. La autenticación del punto de acceso de tokens es none para clientes públicos con PKCE o client_secret_basic.
• Un cliente registrado pero nunca autorizado se elimina después de 24 horas.
• Una solicitud de autorización con prompt=login o max_age exige un nuevo inicio de sesión. Si ya has iniciado sesión, SciFig te pide confirmación antes de cerrarla y volver a iniciarla.
• Los límites de las credenciales OAuth se cuentan por cliente y cuenta, por lo que otros usuarios del mismo asistente no consumen tus límites.

Todas las respuestas incluyen X-Request-Id; los cuerpos de error lo repiten como error.request_id. Identifica la solicitud en nuestros registros sin revelar nada más, por lo que puedes registrarlo y facilitarlo al contactar con soporte.