Claves de APIPróximamente
Crea una clave de API con alcances para tu cuenta de Matchai, úsala como token bearer, protégela, rótala y revócala. Solo para tus scripts y herramientas de IA.
Una clave de API permite que tu propio código actúe en tu propia cuenta de Matchai. Es la forma más sencilla de entrar: no hay ninguna app que registrar ni ningún flujo de inicio de sesión, solo un encabezado en cada solicitud.
Usa una clave para tus propios scripts y tus propias herramientas de IA. Si estás creando algo que usarán otros profesionales, usa Conectar con Matchai en su lugar. Consulta las claves son para tu propia cuenta.
Qué es una clave
- Llega exactamente a una cuenta: la que la creó.
- Tiene los alcances que elegiste al crearla, y nada más. Una clave con
listings:readno puede modificar un anuncio. - Puede revocarse en cualquier momento, por ti, desde Matchai.
- Pertenece a la conexión Acceso a la API de tu cuenta. Acceso a la API es un conector de Matchai, como Claude o ChatGPT, y aparece en la página Conectores. Es una sola conexión sin importar cuántas claves crees, y las claves nunca se facturan una por una. La página Conectores muestra cuánto cuesta la conexión.
Crea una clave
Abre Configuración → Conectores en Matchai y despliega Avanzado (para desarrolladores).
Ve a Claves de API y crea una clave. Ponle un nombre que diga dónde se va a ejecutar, como "Sincronización de anuncios" o "Panel de la oficina". Lo agradecerás cuando tengas cinco.
Elige sus alcances. Escoge solo lo que necesita el código. La tabla de alcances los enumera todos.
Copia la clave. Matchai la muestra una sola vez. Después, la lista solo muestra el nombre de la clave, sus primeros caracteres, sus alcances y cuándo se usó por última vez. Si pierdes una clave, crea una nueva y revoca la anterior.
Formato de la clave
Una clave es matchai_ seguido de una cadena aleatoria larga de letras y dígitos. La parte aleatoria no tiene guiones ni guiones bajos, así que un doble clic selecciona la clave completa y un solo patrón la encuentra:
matchai_[A-Za-z0-9]+Trata una clave como una cadena opaca. No la analices y no dependas de su longitud. El prefijo matchai_ es exclusivo de Matchai, lo que permite que los escáneres de secretos reconozcan una clave que se filtra a un repositorio.
Usa una clave
Envía la clave como token bearer en cada solicitud:
curl https://api.matchai.co/v1/me \
-H "Authorization: Bearer $MATCHAI_API_KEY"Una solicitud que no lleva clave, o que lleva una clave revocada o mal escrita, responde 401.
Protege una clave
- Guárdala en un servidor que controles. Léela desde una variable de entorno o un gestor de secretos. Nunca la pongas en código de navegador, en una app móvil, en un repositorio público, en una línea de registro ni en un mensaje de chat: cualquiera que pueda leerla puede actuar como tú.
- Usa una clave por script o por entorno. Con una clave para desarrollo y otra para producción, puedes revocar una sin detener la otra.
- Dale a cada clave los menos alcances posibles. Un script que solo lee anuncios no necesita
contacts:write. - Revoca una clave en cuanto dudes de ella. Una clave nueva no cuesta nada. Consulta revoca una clave.
Rota una clave
Rota las claves con una frecuencia que puedas mantener, y de inmediato si alguien pudo haber visto una clave. Varias claves funcionan al mismo tiempo, así que la rotación no requiere tiempo de inactividad:
Crea una clave nueva con los mismos alcances.
Implementa la clave nueva en el código que usa la anterior.
Comprueba en la lista de claves que la fecha de último uso de la clave anterior dejó de cambiar.
Revoca la clave anterior.
Todas las claves de una cuenta comparten su conexión Acceso a la API, así que también comparten el límite de solicitudes y el límite de energía de la conexión.
Revoca una clave
Abre Configuración → Conectores → Avanzado (para desarrolladores) → Claves de API y revoca la clave. A partir de ese momento, las solicitudes que la usan responden 401.
Para detener todas las claves a la vez, desconecta Acceso a la API en la página Conectores. Cuando una conexión termina, se detienen todas sus claves.
Las claves son para tu propia cuenta
Una clave personal es para tu propia cuenta. Los términos del servicio de Matchai no te permiten usar claves personales para ofrecer un servicio a otras personas.
Si otros profesionales van a usar lo que creas, como un creador de sitios web, un CRM o un asistente de IA, crea una app de Matchai y usa Conectar con Matchai. Así, cada profesional ve qué puede hacer tu app y quién paga, da su consentimiento con solo presionar Permitir y puede desconectarse cuando quiera. Eso también es lo que hace que sus datos sigan siendo suyos.
Acciones finales
Acceso a la API tiene el mismo ajuste para las acciones finales que cualquier otra conexión, y empieza en Preguntarme. Un script que envía un mensaje, publica un anuncio o elimina algo recibe 202 Accepted y espera a que apruebes la acción en Matchai. Escribe tus scripts para que manejen ambas respuestas: acciones finales muestra cómo.
Errores que puedes encontrar
| Estado | Código o tipo de error | Qué hacer |
|---|---|---|
401 | authentication_error | La clave falta, está mal escrita o fue revocada. Crea una clave nueva. |
402 | insufficient_energy o energy_limit_reached | La cuenta se quedó sin Energía Matchai, o la conexión alcanzó su límite de energía. No se hizo nada. |
403 | scope_missing | A la clave le falta un alcance. El mensaje lo nombra. Crea una clave que lo tenga. |
429 | rate_limited | Demasiadas solicitudes. Espera los segundos que indica Retry-After. |
La página de errores cubre todos los códigos.
AutenticaciónPróximamente
Dos formas de llamar a la API: claves de API para tu cuenta y Conectar con Matchai (OAuth 2.1) para apps. Alcances, acciones finales y límites de energía.
Crea una app de MatchaiPróximamente
Registra la app que los profesionales conectan con Conectar con Matchai: nombre, logo, sitio web, URL de redirección, ID y secreto, modo de prueba y quién paga.