Cómo crear o clonar una clave de API privada

Qué aprenderás

Aprende a crear o clonar una clave de API privada y a elegir ámbitos que controlan a qué puede acceder una aplicación en tu cuenta de Klaviyo.

Tanto las claves de API privadas como los ámbitos te ayudan a proteger tus datos y los de tus clientes al limitar a qué pueden acceder terceros.

Información sobre claves de API privadas y ámbitos

Una llamada a la API permite que una aplicación solicite, añada o edite información en otra aplicación.

Una clave de API privada identifica tu cuenta de Klaviyo y autoriza solicitudes de API mediante los ámbitos asignados a la clave. Cualquiera que tenga la clave puede usar esos permisos, así que trátala como si fuera una contraseña.

Incluir un alcance para una clave de API privada añade otra capa de autorización, lo que limita a qué elementos específicos puede acceder un tercero. Los alcances son similares a la llave de un hotel: solo te dan acceso a ciertas áreas (como tu habitación o el gimnasio) y no a todo el edificio.

Alcance de los niveles de acceso

Cuando crees una clave de API privada, elige un nivel de acceso para cada alcance de la API. Estos niveles de acceso determinan si un tercero puede:

• No tener acceso a los datos o las acciones cubiertos por ese ámbito.
• Ver los datos cubiertos por ese ámbito sin realizar cambios (acceso de lectura).
• Ver datos y crear, eliminar o realizar otros cambios incluidos en ese ámbito (acceso de lectura/escritura).

Por ejemplo, para suscribir perfiles a marketing y añadirlos a una lista de Klaviyo desde otra aplicación, utiliza Suscripción masiva de perfiles. Este punto de conexión requiere lists:write, profiles:write y subscriptions:write. Conceder acceso de lectura/escritura para estos ámbitos cubre esta solicitud; no es necesario conceder acceso a ámbitos no relacionados.

Puedes obtener información sobre las API de Klaviyo y ver los alcances disponibles para cada punto de conexión en el portal de desarrolladores.

Antes de empezar

Ten en cuenta lo siguiente:

• Después de crear una clave de API privada, no puedes:
  • Vuelve a ver la clave de API privada completa después de salir de la página de confirmación.
    • Consejo: guarda de forma segura las claves de API privadas y anota para qué quieres usarlas, por ejemplo, en un gestor de contraseñas.
  • Añade o edita sus ámbitos.
    • Si necesitas diferentes ámbitos, crea una nueva clave de API privada con el acceso requerido. Actualiza las integraciones que usen la clave anterior y confirma que funcionan antes de eliminarla.
• La página de creación se abre con Clave personalizada seleccionada. Elige el acceso de al menos 1 alcance de la API antes de crear la clave.

Si no estás seguro de qué puntos de conexión, ámbitos o permisos de API necesitas, ponte en contacto con un desarrollador o pide ayuda a un socio de Klaviyo.

Crear una clave de API privada

1. Haz clic en el nombre de la empresa en la parte inferior izquierda.
2. Ve a Ajustes.
3. Click clave de API.
   

4. Haz clic en Crear clave de API privada.
5. Asigna un nombre a la clave de API.
6. En Selecciona el nivel de acceso, elige el acceso que necesita la integración:
   • Clave de solo lectura: concede acceso de lectura para todos los alcances de la API disponibles.
   • Clave de acceso completo: concede acceso de lectura/escritura a todos los alcances de la API disponibles.
   • Clave personalizada: te permite elegir Sin acceso, Acceso de lectura o Acceso de lectura/escritura para cada fila en Ámbitos de la API. Selecciona el acceso para al menos un ámbito.

7. Selecciona Crear.
8. En la página de confirmación, usa el icono de copiar (Copiar clave) o el icono de descarga (Descargar (.txt)) para guardar la clave en un lugar seguro. No puedes volver a ver la clave completa después de salir de esta página.
9. Selecciona Cerrar para volver a claves de API.

Ahora, cuando compartas una clave de API privada, el tercero solo tendrá acceso a la información que definiste en el alcance.

Clonar una clave de API privada

La clonación crea una nueva clave de API privada usando los permisos de la clave original. Los permisos renombrados usan sus nombres actuales, y los permisos en desuso sin sustitución se omiten.

Ten en cuenta que:

• La clonación no genera la misma clave que la clave de API privada original.
• Una clave de API clonada tiene el mismo nombre que la original. No puedes cambiarle el nombre en la configuración de claves de API.

Para clonar una clave de API privada:

1. Ve a Configuración > claves de API.
2. Haz clic en el menú de 3 puntos junto a la clave que quieras clonar.
3. Selecciona Clonar y, a continuación, selecciona Clonar de nuevo en el cuadro de diálogo de confirmación.

4. Usa el icono de copiar (Copiar clave) o el icono de descarga (Descargar (.txt)) para guardar la nueva clave en un lugar seguro y, a continuación, selecciona Cerrar. No puedes volver a ver la clave completa después de cerrar esta página.
5. Si vas a reemplazar la clave original, actualiza las integraciones que la usan y confirma que funcionan con la nueva clave. Elimina la original solo cuando ya no sea necesaria.

Uso de parámetros de consulta

El parámetro include añade datos relacionados a una respuesta de API. El parámetro scopes preselecciona permisos en la página de creación de claves de API privadas. Estos son usos avanzados independientes de los parámetros de consulta de URL. Si no estás familiarizado con ellos, trabaja con un desarrollador.

Incluir datos relacionados en una respuesta de la API

Cuando un punto de conexión admite el parámetro de consulta include, tu clave debe tener permiso para leer tanto el recurso solicitado como los datos relacionados.

Por ejemplo, GET /api/profiles/{id}/ recupera un solo perfil y requiere profiles:read. Reemplaza {id} por el ID del perfil.

Para incluir las listas de ese perfil, utiliza GET /api/profiles/{id}/?include=lists con profiles:read y lists:read. El punto de conexión de la colección de perfiles (GET /api/profiles/) no admite incluir listas.

Preselecciona ámbitos en la página de creación

Añade el parámetro de consulta scopes a la URL de creación de la clave de API privada para preseleccionar niveles de acceso en el formulario.

Usa una lista de nombres de ámbito separada por comas. Revisa el acceso seleccionado, introduce un nombre para la clave y selecciona Crear. Luego copia o descarga la clave antes de cerrar la página de confirmación.

Un ejemplo de URL es:
https://www.klaviyo.com/create-private-api-key?scopes=campaigns:read,campaigns:write

Ve a nuestro portal de desarrolladores para ver los ámbitos que puedes usar en esta consulta.

Recursos adicionales