# Autenticación e idempotencia

Credenciales, ámbitos, Idempotency-Key e identificadores de solicitud para cada llamada a la API de SciFig.

Fuente: https://scifig.ai/es/docs/api/authentication

## Autenticación Bearer

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.

## Ámbitos

| Ámbito | Permisos | Tipo de clave API |
| --- | --- | --- |
| figures:read | `GET /jobs`, `GET /jobs/{id}`, `GET /files/{file_id}`, `GET /credits` | Clave de solo lectura; puede no caducar nunca |
| figures:generate | Todo lo incluido en `figures:read` y todos los puntos de acceso `POST` | Clave de generación; caduca después de 30 días, 90 días o 1 año; requiere una suscripción activa o un saldo positivo de créditos adquiridos en paquetes |

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.

## Idempotencia

- 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](/es/docs/api/files#upload).
- 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.

## Clientes OAuth

- 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.

## Identificadores de solicitud

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.