Saltar al contenido principal

Autenticación

La API de KintiSoft utiliza API Keys para identificar las integraciones y controlar el acceso a los recursos protegidos.

Las credenciales se envían mediante el encabezado HTTP Authorization, utilizando el esquema Bearer.

¿Cómo funciona?​

Para realizar una solicitud autenticada necesitas:

  1. Tener acceso a un tenant de KintiSoft.
  2. Contar con una API Key válida.
  3. Utilizar la URL base correspondiente.
  4. Incluir la credencial en el encabezado de la solicitud.

El servidor utiliza la información de autenticación y autorización para determinar si la operación puede realizarse.

Obtener una API Key​

La documentación de KintiSoft contempla la administración de API Keys desde el panel de configuración.

Ruta documentada:

Configuración → API → API Keys

Desde allí, cuando la funcionalidad esté habilitada y el usuario tenga los permisos necesarios, podrás administrar las credenciales de integración.

información

La disponibilidad de esta opción depende de la configuración y los permisos de tu cuenta. Contacta al administrador de KintiSoft si no puedes acceder a ella.

Encabezado de autenticación​

Incluye tu API Key en el encabezado Authorization:

Authorization: Bearer YOUR_API_KEY

Reemplaza YOUR_API_KEY por una credencial válida.

No incluyas comillas adicionales alrededor del valor ni publiques la clave en ejemplos compartidos.

Ejemplo con cURL​

Puedes almacenar la credencial en una variable de entorno y utilizarla en tus solicitudes.

export KINTISOFT_API_KEY="YOUR_API_KEY"
export KINTISOFT_BASE_URL="https://acme.api.kintisoft.com/v1"

Después, realiza una solicitud a un recurso autorizado:

curl --request GET \
  "${KINTISOFT_BASE_URL}/RUTA_DEL_RECURSO" \
  --header "Authorization: Bearer ${KINTISOFT_API_KEY}" \
  --header "Accept: application/json"
aviso

RUTA_DEL_RECURSO es un marcador de posición. Utiliza un endpoint publicado en la API Reference.

No compartas comandos que contengan credenciales reales.

Ejemplo con JavaScript​

const baseUrl = process.env.KINTISOFT_BASE_URL;
const apiKey = process.env.KINTISOFT_API_KEY;

async function getResource(resourcePath) {
  const response = await fetch(
    `${baseUrl}/${resourcePath}`,
    {
      method: "GET",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        Accept: "application/json",
      },
    }
  );

  if (!response.ok) {
    throw new Error(
      `La solicitud falló: HTTP ${response.status}`
    );
  }

  return response.json();
}

Este ejemplo está pensado para un entorno de ejecución del lado del servidor.

:::danger Seguridad Nunca incluyas tu API Key privada en JavaScript ejecutado directamente en el navegador ni en aplicaciones públicas. :::

Identificación del tenant​

KintiSoft utiliza subdominios para identificar el contexto de cada tenant.

La documentación actual establece la siguiente estructura:

https://{tenant}.api.kintisoft.com/v1

Por ejemplo:

https://acme.api.kintisoft.com/v1

El subdominio identifica el contexto solicitado.

La API Key debe estar autorizada para operar dentro de ese contexto.

Según el mecanismo documentado actualmente, no necesitas enviar un identificador adicional de tenant, empresa u organización en el encabezado de autenticación.

Autenticación y autorización​

Aunque están relacionadas, cumplen funciones diferentes.

ConceptoFunción
AutenticaciónVerifica la credencial utilizada.
AutorizaciónDetermina si la operación está permitida.
TenantDelimita el contexto de acceso a recursos.
PermisosRestringen las operaciones disponibles.

Una API Key válida no garantiza acceso a todos los recursos de KintiSoft.

La operación solicitada debe estar permitida para la integración.

Errores de autenticación​

Credencial ausente​

Si una solicitud no incluye el encabezado de autorización, puede ser rechazada.

Ejemplo documentado:

{
  "error": {
    "code": "missing_authorization_header",
    "message": "Authorization header is required."
  }
}

API Key inválida​

Una credencial incorrecta o no reconocida puede generar una respuesta como:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid."
  }
}

Permisos insuficientes​

Una integración autenticada puede carecer de autorización para ejecutar determinada operación.

Ejemplo documentado:

{
  "error": {
    "code": "insufficient_permissions",
    "message": "You do not have permission to access this resource."
  }
}

Estos ejemplos corresponden a los formatos publicados en la documentación actual. Verifica su comportamiento con la versión de API utilizada por tu integración.

Para conocer más situaciones, consulta Errores y respuestas.

Seguridad de credenciales​

Las API Keys son información sensible.

Almacenamiento seguro​

Utiliza variables de entorno o servicios especializados para administrar secretos.

Evita almacenar claves en:

  • Repositorios públicos.
  • Código frontend.
  • Aplicaciones móviles sin mecanismos de protección.
  • Archivos compartidos.
  • Registros de aplicación.

Permisos mínimos​

Asigna únicamente los permisos necesarios para cada integración.

Si una aplicación solo necesita consultar información, evita otorgarle permisos de escritura cuando existan opciones de acceso restringido.

Rotación y revocación​

Establece procedimientos para reemplazar credenciales y revocar claves que hayan dejado de utilizarse.

Si sospechas que una API Key se ha expuesto, solicita su revocación y reemplazo.

HTTPS​

Todas las solicitudes a la API deben utilizar conexiones HTTPS.

No transmitas credenciales mediante HTTP sin cifrar.

Buenas prácticas​

  • Utiliza credenciales diferentes para integraciones independientes cuando sea posible.
  • Separa las credenciales de prueba y producción si tu entorno lo permite.
  • Nunca compartas claves en capturas de pantalla.
  • Evita incluir credenciales en parámetros de URL.
  • Comprueba los permisos antes de desplegar una integración.
  • Gestiona los errores de autenticación sin exponer información sensible.

Recursos relacionados​