---
title: "Autenticación"
description: "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."
last_updated: "2026-10-21"
lang: "es"
status: "coming-soon"
canonical: "https://matchai.co/docs/es/developers/authentication"
---
# Autenticación
> 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.
**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
Cada solicitud a la API de Matchai actúa en nombre de **una cuenta de Matchai**. Hay dos formas de obtener la credencial que lo demuestra, y la adecuada depende de quién es la cuenta con la que trabajas.
## Dos formas de entrar [#two-ways-in]
| | Claves de API | Conectar con Matchai |
|---|---|---|
| Para qué sirve | Tus propios scripts y tus propias herramientas de IA, en tu propia cuenta | Una app que da servicio a otros profesionales: un creador de sitios web, un CRM, un asistente de IA |
| Quién concede el acceso | Tú, cuando creas la clave | El profesional, al presionar **Permitir** |
| Credencial | Una clave que empieza con `matchai_` | Un token de acceso OAuth 2.1, con un token de actualización |
| Alcances | Se eligen al crear la clave | Los solicita tu app y se le muestran al profesional |
| Configuración | Crea una clave en Matchai | [Crea una app de Matchai](https://matchai.co/docs/es/developers/authentication/create-a-matchai-app) y luego ejecuta el [flujo OAuth](https://matchai.co/docs/es/developers/authentication/connect-with-matchai) |
| Cómo termina | Revocas la clave | El profesional presiona **Desconectar** |
Ambas van en el mismo encabezado:
```http title="Request header"
Authorization: Bearer matchai_…
```
Un token de acceso OAuth se envía de la misma forma, en lugar de la clave.
Crea una clave para tu propia cuenta, define sus alcances, rótala y revócala.
Registra la app a la que se conectarán los profesionales.
El flujo OAuth 2.1, la página de autorización y un ejemplo de código completo.
Una clave o un token está vinculado a la cuenta que lo concedió, así que nunca puede leer los anuncios, los contactos ni los mensajes de otro profesional. Una app que da servicio a tres corredores tiene tres conexiones, cada una con sus propios tokens, sin importar cómo esté construida. Por eso, además, una clave personal no puede usarse para ofrecer un servicio a otras personas: dar servicio a otros profesionales pasa por Conectar con Matchai, donde cada uno da su consentimiento.
## Lo que puede hacer una solicitud [#what-a-request-can-do]
Una solicitud puede hacer lo mismo que el titular de la cuenta puede hacer en Matchai, con las mismas reglas y los mismos permisos, y nada más. Dos cosas la limitan todavía más:
- **Los alcances** limitan qué partes de la cuenta puede tocar la credencial.
- **Las acciones finales** esperan la aprobación del titular de la cuenta, a menos que haya permitido que tu app las ejecute.
`GET /v1/me/connection` ([`getConnection`](https://matchai.co/docs/developers/api-reference/me/getConnection)) le dice a tu app cómo está conectada: la app, los alcances concedidos, `auth_type` (`api_key` u `oauth`), `approval_mode` (`ask_me` o `allowed`) y si la conexión está en modo de prueba.
## Alcances [#scopes]
Cada operación de la [referencia de la API](https://matchai.co/docs/developers/api-reference) enumera los alcances que necesita. Pide solo lo que tu app usa: es más probable que un profesional presione **Permitir** cuando la lista es corta y cada línea tiene sentido.
| Alcance | Qué permite |
|---|---|
| `profile:read` | Leer el perfil, el idioma, la zona horaria y el estado de energía de la cuenta |
| `profile:write` | Cambiar el perfil de la cuenta |
| `listings:read` | Leer los anuncios, sus fotos, habitaciones, documentos y traducciones |
| `listings:write` | Crear y editar anuncios, sus fotos, habitaciones y traducciones, y eliminarlos |
| `listings:publish` | Publicar y despublicar anuncios |
| `sites:read` | Leer los sitios de Matchai y los anuncios que contienen |
| `sites:write` | Crear, editar y publicar sitios de Matchai, y elegir sus anuncios |
| `page:read` | Leer la Página Matchai y sus enlaces |
| `page:write` | Editar y publicar la Página Matchai, sus enlaces y sus archivos |
| `contacts:read` | Leer los contactos y los detalles de los prospectos |
| `contacts:write` | Agregar, editar, convertir y eliminar contactos, y registrar las consultas del sitio web |
| `messages:read` | Leer conversaciones, mensajes y correos electrónicos enviados, marcar conversaciones como leídas o archivarlas, y redactar borradores de respuesta |
| `messages:send` | Enviar mensajes y correos electrónicos, e iniciar conversaciones, en nombre del titular de la cuenta |
| `calendar:read` | Leer la disponibilidad y las citas |
| `calendar:write` | Cambiar la disponibilidad, reservar y cambiar citas, y registrar solicitudes de visita |
| `documents:read` | Leer los documentos de Matchai Cloud y los enlaces de entrega |
| `documents:write` | Subir, archivar, etiquetar, compartir y enviar a la papelera documentos, y crear enlaces de entrega |
| `teams:read` | Leer los equipos, sus miembros y sus invitaciones |
| `teams:write` | Crear y administrar equipos, e invitar o quitar miembros |
| `projects:read` | Leer los proyectos, sus miembros, equipos y anuncios |
| `projects:write` | Crear y administrar proyectos, e invitar o quitar miembros |
| `notifications:read` | Leer las notificaciones y las preferencias de notificación |
| `notifications:write` | Marcar notificaciones como leídas y cambiar las preferencias de notificación |
| `saved_listings:read` | Leer los anuncios que la cuenta guardó |
| `saved_listings:write` | Guardar anuncios y quitarlos de guardados |
| `analytics:read` | Leer la analítica de los anuncios, incluida la actividad de IA |
| `webhooks:manage` | Administrar las suscripciones de webhook y leer los eventos |
Cuando a una credencial le falta un alcance, la llamada falla con `403` y el código `scope_missing`, y el mensaje nombra el alcance. Si es una clave, crea una clave nueva que tenga el alcance y [revoca la anterior](https://matchai.co/docs/es/developers/authentication/api-keys#rotate-a-key). Si es una conexión OAuth, haz que el profesional vuelva a pasar por el [flujo de conexión](https://matchai.co/docs/es/developers/authentication/connect-with-matchai) de tu app, para que pueda aceptar la lista más larga.
Algunas operaciones no necesitan ningún alcance porque solo trabajan con lo que ya es público, como consultar el perfil publicado de un profesional. Están marcadas como **Free** (gratis) en la referencia, y para ellas la clave o el token son opcionales.
## Acciones finales [#final-actions]
Cuatro tipos de acciones son **finales**: enviarle algo a otra persona, publicar algo para el público, pagar y eliminar contenido de la cuenta. El Asistente de Matchai siempre pregunta antes de hacer cualquiera de ellas, y la API somete a tu app a la misma regla. Cada acción final está marcada como **Final action** (acción final) en la referencia.
El titular de la cuenta elige cómo maneja tu app estas acciones, por conexión:
| Ajuste | Qué pasa cuando tu app llama a una acción final |
|---|---|
| **Preguntarme** (el predeterminado) | La llamada no se ejecuta. Devuelve `202 Accepted` y espera a que el titular de la cuenta la apruebe en Matchai. |
| **Permitido** | La llamada se ejecuta de inmediato y devuelve su respuesta habitual. |
Todo lo que no es una acción final se ejecuta según los alcances de la credencial, igual que la misma edición en la app: lecturas, borradores y cambios en los propios registros del titular de la cuenta. Eliminar la configuración de tu propia app, como una suscripción de webhook, tampoco es una acción final.
**Escribe tu app para ambos ajustes.** El titular de la cuenta puede cambiar el ajuste en cualquier momento, así que nunca des por hecho cuál vas a recibir.
### Sigue una aprobación [#follow-an-approval]
Una acción final en modo **Preguntarme** responde `202` y todavía no hace nada:
```json title="Response (202)"
{
"status": "pending_approval",
"approval_id": "1e2f3a4b-5c6d-4e7f-8a8b-9c0d1e2f3a4b",
"approval_url": "https://matchai.co/approvals/1e2f3a4b-5c6d-4e7f-8a8b-9c0d1e2f3a4b",
"expires_at": "2026-10-25T13:05:00Z",
"summary": "Send a message to Julien Bouchard"
}
```
**Avísale a la persona.** Matchai notifica al titular de la cuenta, que aprueba o rechaza en una página que describe la acción en palabras sencillas. Muestra `summary` en tu propia interfaz y enlaza a `approval_url`, para que la persona pueda responder desde donde esté.
**Espera el resultado.** El webhook `approval.resolved` llega cuando se responde la solicitud, o cuando vence. También puedes consultar periódicamente `GET /v1/approvals/{approval_id}` ([`getApproval`](https://matchai.co/docs/developers/api-reference/approvals/getApproval)). Los webhooks son la mejor opción: nadie tiene que adivinar cuánto tarda una persona.
**Lee el resultado.** Cuando la solicitud está `approved`, Matchai ejecutó la llamada **exactamente como la enviaste**, y `result` contiene el estado y el cuerpo que devolvió la llamada. Envía exactamente el texto que vio la persona. Nunca reescribas un borrador que aprobó.
Una aprobación tiene uno de cinco estados:
| Estado | Significado |
|---|---|
| `pending` | Esperando al titular de la cuenta. No ha pasado nada. |
| `approved` | Aprobada, y Matchai ejecutó la llamada. `result` contiene el resultado. |
| `declined` | El titular de la cuenta dijo que no. No pasó nada. |
| `expired` | Nadie respondió antes de `expires_at`. No pasó nada. |
| `cancelled` | Tu app retiró la solicitud con `POST /v1/approvals/{approval_id}/cancel` ([`cancelApproval`](https://matchai.co/docs/developers/api-reference/approvals/cancelApproval)). |
`GET /v1/approvals` ([`listApprovals`](https://matchai.co/docs/developers/api-reference/approvals/listApprovals)) enumera las solicitudes que hizo tu conexión, y acepta un filtro `status`.
Envía un `Idempotency-Key` con cada acción final. Si tu solicitud excede el tiempo de espera y la repites con la misma clave, recibes la misma aprobación pendiente en lugar de una segunda.
Este ejemplo publica un anuncio y maneja ambos ajustes:
```js title="publish.mjs"
import { randomUUID } from 'node:crypto';
const response = await fetch(`https://api.matchai.co/v1/listings/${listingId}/publish`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MATCHAI_API_KEY}`,
'Idempotency-Key': randomUUID(),
},
});
if (response.status === 202) {
// Ask me: nothing has happened yet.
const pending = await response.json();
console.log(`Waiting: ${pending.summary}`);
console.log(`The account holder can answer at ${pending.approval_url}`);
} else if (response.ok) {
// Allowed: the listing is published now.
const listing = await response.json();
console.log(`Published at ${listing.url}`);
} else {
const { error } = await response.json();
throw new Error(`${error.code}: ${error.message}`);
}
```
## Límites de energía [#energy-limits]
Algunas acciones gastan Energía Matchai, igual que las funciones de IA en la app: escribir un anuncio con IA, editar fotos, traducir, redactar con IA, enviar un correo electrónico y los mensajes que salen por SMS. La referencia marca cada una de ellas e indica qué tan pesada es la acción: ligera, moderada, pesada o variable.
- **La API nunca muestra la energía como un número.** `GET /v1/me` devuelve su estado: `full`, `comfortable`, `low` o `empty`.
- **Una llamada que necesita más de lo que queda no hace nada.** Responde `402` con el código `insufficient_energy`, y no se gasta nada.
- **El titular de la cuenta puede fijar un límite de energía para cada conexión**, para que un script descontrolado se detenga en un tope que eligió. Cuando tu conexión lo alcanza, las llamadas que gastan energía responden `402` con el código `energy_limit_reached`, y `GET /v1/me/connection` informa `energy_limit_reached: true`.
Muéstrale a la persona el `message` de un `402`: dice qué pasó y qué hacer a continuación. Consulta [errores](https://matchai.co/docs/es/developers/errors#insufficient_energy).
## Terminar una conexión [#ending-a-connection]
Una conexión termina de una de tres formas, y cada una detiene todas las credenciales que le pertenecen:
- El profesional presiona **Desconectar** en la página Conectores.
- Revocas una [clave de API](https://matchai.co/docs/es/developers/authentication/api-keys#revoke-a-key).
- Tu app llama a `DELETE /v1/me/connection` ([`disconnect`](https://matchai.co/docs/developers/api-reference/me/disconnect)). Termina la conexión como si el profesional hubiera presionado **Desconectar**, y no elimina nada de la cuenta.
Después de que una conexión termina, sus suscripciones de webhook se desactivan y sus solicitudes responden `401`. Interprétalo como "hay que volver a conectarse", no como una interrupción del servicio.
## Modo de prueba [#test-mode]
Una app que está conectada solo a la cuenta de su propio desarrollador está en **modo de prueba**. Las conexiones de prueba no se facturan, y los eventos que producen llevan `test_mode: true`. [Crea una app de Matchai](https://matchai.co/docs/es/developers/authentication/create-a-matchai-app#test-mode) explica cómo funciona y quién paga cuando se conectan otros profesionales.
Qué significa cada estado y cada código, y qué hacer al respecto.
Cómo se limitan las solicitudes por conexión.
Alcances, precios y acciones finales de cada endpoint.
## 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)