Obtén una clave de API de Sintropix para agentes e integraciones

1

Inicia sesión y abre Tu cuenta

Inicia sesión como el Usuario en cuyo nombre actuará la clave. La clave actúa con las Membresías de Organización de ese Usuario y sus Roles, así que elige un Usuario con el acceso que la integración realmente necesita.El inicio de sesión siempre pide la Verificación en dos pasos. Por defecto, Sintropix te envía un código de 6 dígitos por correo después de la contraseña. El código vence a los 5 minutos. Haz clic en Enviar otro código para recibir uno nuevo; solo sirve el último. Después de 5 códigos incorrectos, debes ingresar tu contraseña de nuevo.Tu primer inicio de sesión empieza en el enlace para definir tu contraseña que Sintropix te envía por correo. Elige una contraseña de entre 8 y 128 caracteres y haz clic en Guardar contraseña. Sintropix inicia tu sesión y te envía un código por correo para activar la verificación en dos pasos, así que escribes tu contraseña una sola vez. Si inicias sesión desde la página de inicio de sesión antes de activar la verificación en dos pasos, Sintropix te envía el código justo después de la contraseña. Si el enlace ya se usó o venció, la página muestra Enlace no válido. Haz clic en Pedir un enlace nuevo para solicitar otro.Si olvidaste tu contraseña, haz clic en ¿Olvidaste tu contraseña? en la página de inicio de sesión e ingresa tu correo. Si la dirección tiene una cuenta en Sintropix, recibes un enlace para elegir una contraseña nueva. El enlace vence en 1 hora y sirve una sola vez. Al guardar la contraseña nueva se cierran todas tus sesiones; luego Sintropix inicia tu sesión en la misma página y te pide el segundo factor.Si prefieres una aplicación de autenticación, elige Usar una aplicación de autenticación durante la configuración. Para entonces, Sintropix ya te envió un código por correo, que puedes ignorar. También puedes cambiar más tarde: haz clic en Configurar aplicación de autenticación en Tu cuenta > Seguridad. Escaneas un código QR, confirmas un código y guardas 10 códigos de respaldo. Desde entonces, el inicio de sesión pide el código de la aplicación o un código de respaldo, y Sintropix deja de enviarte códigos por correo. Solo una sesión con verificación en dos pasos puede crear claves de API.Haz clic en tu nombre, en la parte inferior de la barra lateral izquierda, y elige Tu cuenta.

2

Ve a Claves de API

Tu cuenta se abre en Perfil. En la lista de la izquierda, haz clic en Claves de API. La página está en https://app.sintropix.com/account/api-keys.La página lista todas las claves que te pertenecen con su nombre, prefijo, fecha de creación, vencimiento y último uso. Puedes revocar una clave desde el ícono de papelera de cada fila.

3

Crea la clave

Haz clic en Crear clave. Dale a la clave un nombre descriptivo (por ejemplo erwin-agent o reconciliation-bot) para poder identificarla después en la lista de claves y en el registro de auditoría.Si el Usuario propietario pertenece a más de una Entidad, el diálogo muestra además un selector Entidad legal. Déjalo en Todas las entidades legales para que la clave actúe sobre todas las Entidades a las que el Usuario ya tiene acceso, o elige una Entidad para acotar la clave a esa única empresa. Una clave acotada no puede leer ni escribir los datos de las otras Entidades, y la restricción se ve en la columna Entidad legal de la lista de claves.Elige una sola Entidad cuando la integración solo necesita trabajar con una empresa (por ejemplo, un bot contable que atiende a un solo cliente), para que una clave filtrada no pueda tocar el resto.Haz clic en Crear clave en el diálogo para generar la clave.

4

Copia el secreto

La clave se muestra una sola vez. Cópiala con el botón junto al campo y guárdala en tu gestor de secretos antes de hacer clic en Listo. Sintropix no vuelve a mostrar el secreto después de esta pantalla; si lo pierdes, revoca la clave y crea una nueva.

5

Llama a la API

Envía la clave en el encabezado x-api-key en cada solicitud:

curl https://api.sintropix.com/api/entities \
  -H "x-api-key: $SINTROPIX_API_KEY"

Toda solicitud que modifica datos (POST, PUT, PATCH, DELETE) hecha con una clave debe enviar además dos encabezados:

• x-audit-actor nombra al software que actúa (por ejemplo my-agent).
• x-audit-reason explica por qué se realiza el cambio, en una sola línea de texto plano de hasta 500 caracteres.

POST /api/feedback es la única excepción: no necesita ninguno de los dos encabezados, y también puede enviarla una clave de solo lectura.Ambos valores se registran tal cual en el sobre del registro de auditoría. Omitir x-audit-actor devuelve 400 con el código AUDIT_ACTOR_REQUIRED_ERROR. Un x-audit-reason ausente o vacío devuelve 400 con el código AUDIT_REASON_REQUIRED_ERROR; un valor de más de 500 caracteres devuelve 400 con el código AUDIT_REASON_TOO_LONG_ERROR.

curl -X POST https://api.sintropix.com/api/entities/$ENTITY_ID/partners \
  -H "x-api-key: $SINTROPIX_API_KEY" \
  -H "x-audit-actor: my-agent" \
  -H "x-audit-reason: Crear Servicios Cloud SpA desde el correo de onboarding de julio" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "0b6c0f2e-5a4d-4e8f-b1c3-7d9e2a4f6c88",
    "name": "Servicios Cloud SpA",
    "country": "CL",
    "taxId": "76123456-0"
  }'

Las solicitudes a /api/auth/* se rechazan cuando llevan x-api-key, así que una clave no puede usarse para crear más claves ni para administrar Usuarios.Las solicitudes hechas con una clave de API no piden un código de verificación en dos pasos. El segundo factor se comprueba una sola vez, al crear la clave.

​

Alcance y permisos

• Una clave se autentica como su Usuario propietario, con las Membresías de Organización de ese Usuario. Consulta Acceso y roles.
• Una clave nunca hace trabajo de Superadmin, aunque sea de un Superadmin. Administrar Usuarios, Organizaciones y Membresías requiere una sesión iniciada; una clave recibe 403 con SUPERADMIN_SESSION_REQUIRED.
• Las rutas de negocio están acotadas por Entidad (/api/entities/{entityId}/...). Una clave solo puede acceder a las Entidades de las Organizaciones en las que el Usuario propietario tiene una Membresía, y solo puede hacer lo que el Rol del Usuario allí permite. Una clave de un viewer solo puede leer.
• Una clave creada para una sola Entidad queda acotada a esa Entidad. Las solicitudes a /api/entities/{otherEntityId}/... devuelven 404, GET /api/entities lista solo la Entidad acotada y GET /api/organizations devuelve un arreglo vacío. La clave alcanza los Partners de la Organización de su Entidad, pero solo puede fusionar un Partner que ninguna otra Entidad usa. También alcanza las Dimensiones de esa Organización. Lista todas las Integraciones de esa Organización, nunca un secreto, pero no puede conectar, renovar ni desconectar ninguna (403 con PERMISSION_DENIED_ERROR), y solo agrega o quita los feeds que llegan a su propia Entidad. Cualquier otra Organización responde 404. Las rutas que administran una Organización completa, como Agent Channels, los asientos intercompañía (también al leer) y GET /api/organizations/{organizationId}/role, devuelven 403. Ninguna clave de API puede crear Entidades. Usa claves de una sola Entidad cuando la integración solo deba tocar una empresa.

​

Límites de solicitudes

​

Rotación y revocación

• Rota las claves de forma periódica y cada vez que un miembro del equipo con acceso deje la empresa.
• Revoca una clave de inmediato desde Tu cuenta → Claves de API si sospechas que se filtró. La revocación aplica desde la siguiente solicitud.
• Toda acción realizada con una clave queda registrada en el registro de auditoría bajo el Usuario propietario, así que la actividad de una clave filtrada es rastreable.