---
title: "Claves de API"
description: "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."
last_updated: "2026-10-21"
lang: "es"
status: "coming-soon"
canonical: "https://matchai.co/docs/es/developers/authentication/api-keys"
---
# Claves de API
> 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.
**Próximamente. Esto se documenta antes del lanzamiento para que puedas planificar tu integración; todavía no está disponible.**
Source: https://matchai.co/docs/es/developers/authentication/api-keys
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](https://matchai.co/docs/es/developers/authentication/connect-with-matchai) en su lugar. Consulta [las claves son para tu propia cuenta](#keys-are-for-your-own-account).
## Qué es una clave [#what-a-key-is]
- **Llega exactamente a una cuenta**: la que la creó.
- **Tiene los alcances que elegiste** al crearla, y nada más. Una clave con `listings:read` no 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 [#create-a-key]
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](https://matchai.co/docs/es/developers/authentication#scopes) 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 [#key-format]
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:
```text title="Pattern"
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 [#use-a-key]
Envía la clave como token bearer en cada solicitud:
```bash title="Terminal"
curl https://api.matchai.co/v1/me \
-H "Authorization: Bearer $MATCHAI_API_KEY"
```
```js title="client.mjs"
export async function matchai(path, init = {}) {
const response = await fetch(`https://api.matchai.co/v1${path}`, {
...init,
headers: {
...init.headers,
Authorization: `Bearer ${process.env.MATCHAI_API_KEY}`,
},
});
if (!response.ok && response.status !== 202) {
const { error } = await response.json();
throw new Error(`${error.code}: ${error.message} (request ${error.request_id})`);
}
return response;
}
```
```python title="client.py"
import os
import requests
def matchai(method, path, **kwargs):
headers = {"Authorization": f"Bearer {os.environ['MATCHAI_API_KEY']}"}
headers.update(kwargs.pop("headers", {}))
response = requests.request(
method, f"https://api.matchai.co/v1{path}", headers=headers, timeout=30, **kwargs
)
if not response.ok:
error = response.json()["error"]
raise RuntimeError(f"{error['code']}: {error['message']} (request {error['request_id']})")
return response
```
Una solicitud que no lleva clave, o que lleva una clave revocada o mal escrita, responde `401`.
## Protege una clave [#keep-a-key-safe]
- **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](#revoke-a-key).
## Rota una clave [#rotate-a-key]
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](https://matchai.co/docs/es/developers/rate-limits) y el límite de energía de la conexión.
## Revoca una clave [#revoke-a-key]
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 [#keys-are-for-your-own-account]
Una clave personal es para tu propia cuenta. Los [términos del servicio](https://matchai.co/terms) 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](https://matchai.co/docs/es/developers/authentication/create-a-matchai-app) y usa [Conectar con Matchai](https://matchai.co/docs/es/developers/authentication/connect-with-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 [#final-actions]
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](https://matchai.co/docs/es/developers/authentication#final-actions) muestra cómo.
## Errores que puedes encontrar [#errors-you-may-meet]
| 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](https://matchai.co/docs/es/developers/errors) cubre todos los códigos.
Haz tus primeras llamadas con una clave nueva.
Para las apps que dan servicio a otros profesionales.
Alcances, acciones finales y límites de energía.
## Sitemap
- [Todas las páginas de la documentación de Matchai](https://matchai.co/docs/sitemap.md)
- [llms.txt](https://matchai.co/docs/es/llms.txt)