AdAce AdsClaves de API de AdAce Ads: alcances, caducidad, verificación y revocación
Una clave de API de AdAce Ads autentica un cliente MCP compatible o una integración REST sin necesidad de iniciar sesión de forma interactiva en cada solicitud. Es una credencial, no un token de Google o Meta. Crea una solo para una integración y espacio de trabajo específicos, empieza con el alcance mínimo y comprueba qué puede leer realmente la integración.
Qué autoriza una clave
Una clave está vinculada a su espacio de trabajo y usuario. Sus permisos efectivos son la intersección entre los alcances de la clave y el rol actual del usuario, y la aplicación comprueba el acceso del cliente. Por tanto, un cambio de rol puede reducir lo que una clave existente puede hacer. Copiar el identificador de un espacio de trabajo en una solicitud no otorga acceso a dicho espacio. Usa la lectura para informes; una clave no puede otorgar acceso de forma independiente a un cliente no asignado o a la cuenta de un proveedor desconectado.
El valor completo ak_prefix_secret se devuelve una sola vez al crearlo, mientras que AdAce Ads almacena un hash para su verificación. El prefijo mostrado identifica la clave sin revelar su valor completo. Guarda la credencial completa en la configuración de secretos aprobada de la integración receptora. No la incluyas en mensajes de IA comunes, URLs, código fuente, capturas de pantalla ni registros de depuración. Si pierdes el valor guardado, no podrás recuperarlo a partir del prefijo: crea una de sustitución y revoca la clave extraviada.
A través de REST, las claves permiten lecturas y, con el alcance de propuesta, la creación de propuestas de cambios; no permiten directamente la aprobación, ejecución ni cambios de configuración. Sin embargo, una propuesta no es intrínsecamente inerte: la política automática configurada de un cliente puede procesar una propuesta apta dentro de los permisos y límites aplicables. MCP también aplica comprobaciones de alcance y rol a sus herramientas disponibles. Usa la lectura para un ensayo de informes en lugar de asumir que proponer garantiza una revisión humana de cada acción posterior.
Por ejemplo, crea una clave de lectura llamada «Informe semanal North Store» con una caducidad adecuada al periodo de revisión. Configura el cliente compatible para que la envíe como credencial Authorization Bearer al endpoint documentado. Llama a get_started a través de MCP y luego lee la lista de cuentas del cliente permitido. Compara una cuenta reconocible con la aplicación. Esto confirma una ruta de lectura útil sin crear propuestas ni modificar la publicidad.
Credenciales con propietario y propósito claros
- Asigna a cada integración de confianza una credencial reconocible para que la autoría y el propósito queden claros al revisar los accesos más adelante.
- Limita el acceso mediante alcances, los permisos del usuario actual y la vinculación al espacio de trabajo en lugar de compartir contraseñas de agencia o tokens de proveedores.
- Sustituye la credencial de una integración cuando sea necesario y verifica el reemplazo antes de eliminar la credencial obsoleta durante la rotación rutinaria.
Crear, verificar y rotar
- Abre Conectar IA → Claves de API en el espacio de trabajo deseado. Revisa los nombres existentes, el recuento de claves activas y las marcas de tiempo de último uso antes de crear otra credencial.
- Crea una clave con nombre y permiso de lectura para la primera verificación. Selecciona una caducidad si procede y completa cualquier requisito de segundo factor exigido por la aplicación.
- Guarda el valor único directamente en la configuración de secretos de la integración de confianza. Conserva solo su nombre, prefijo, propietario, propósito y caducidad en tu inventario de accesos.
- Usa la integración para realizar una lectura permitida. Comprueba tanto los datos devueltos como la actividad relevante o el registro de último uso; la marca de tiempo de último uso de la clave se actualiza como máximo una vez por minuto.
- Para la rotación rutinaria, crea y verifica la clave de sustitución, cambia la integración y revoca la clave antigua. Si una clave queda expuesta, revócala de inmediato e investiga su actividad antes de configurar una de reemplazo.
Límites, errores y credenciales expuestas
- Límite de creación: la implementación permite cinco claves activas por persona en un espacio de trabajo. Las claves caducadas o revocadas ya no ocupan espacio activo. Revisa las integraciones obsoletas en lugar de compartir una clave para evitar alcanzar el límite.
- Error 401 o credencial rechazada: comprueba el endpoint, el encabezado Bearer, el valor completo, la caducidad y la revocación. Error 403: comprueba el espacio de trabajo, el alcance efectivo, el rol actual y la asignación del cliente. No se debe ampliar una clave de lectura solo porque se rechazó una solicitud de configuración o propuesta.
- Una respuesta de límite de frecuencia (rate limit) requiere esperar según el encabezado Retry-After y reducir las llamadas repetidas; no significa que la clave haya sido revocada. La revocación de una clave bloquea la autenticación posterior, pero no elimina informes anteriores ni deshace cambios. Las pruebas locales verifican reglas de implementación, no la aceptación de integraciones en producción ni la disponibilidad pública de pago.
Fuentes y lecturas recomendadas
Pruébalo en tus propias cuentas
Crea un espacio de trabajo, conecta Google o Meta en un par de clics y visualiza tus cuentas con claridad. Los cambios siguen tus aprobaciones o la política que configures.
Crea tu espacio de trabajo