Autenticación

Cómo crear tu API key, qué son los scopes y cómo mantener la key segura.

La API de Meteor se autentica con una API key secreta. Cada request lleva la key en el header Authorization, y la key define a qué workspace pertenece y qué puede hacer (sus scopes).

Formato de la key

Todas las keys empiezan con un prefijo que indica su tipo:

• met_live_… — key de producción. Ejecuta acciones reales y consume Energía.
• met_test_… — key de modo test: runs sin costo, ideal para desarrollar. Los efectos externos (mandar WhatsApp, ejecutar integraciones) quedan bloqueados. No es un sandbox aislado: los scopes no restringidos siguen leyendo y escribiendo el workspace real.

La key es un secreto de servidor. Nunca la pongas en el navegador, en una app móvil, ni la subas al control de versiones. Si se filtra, revócala desde el panel y genera una nueva.

Crear una key

Desde tu panel de Meteor: Ajustes → Desarrolladores → Crear API key. Eliges los scopes que necesita y el entorno (live o test). La key se muestra una sola vez — guárdala apenas la creas.

Puedes crear y administrar keys aunque el workspace todavía no tenga plan. Para usarlas, el workspace necesita un plan mensual vigente de Meteor; un trial o un plan bonificado también habilitan la operación. Los Tech Partners aprobados pueden recibir un plan especial de USD 0 de cargo fijo mensual, habilitado únicamente por Meteor, con la Energía a tarifa premium.

Usar la key

Guárdala en una variable de entorno, nunca hardcodeada:

export MET_API_KEY=met_live_tu_key_aqui

Con el SDK:

import Met from '@meteor.ia/sdk';

const met = new Met(process.env.MET_API_KEY, { workspaceId: 7 });

import os
from meteor_ia import Met

met = Met(os.environ["MET_API_KEY"], workspace_id=7)

Con curl, la key va como Bearer token:

curl https://api.met.meteor.com.co/api/v1/workspaces/7/runs \
  -H "Authorization: Bearer $MET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Hola"}'

Saber con qué identidad estás entrando

Una key no dice de quién es con solo mirarla. Para preguntárselo al servidor está GET /me: devuelve la identidad que la API le reconoce a la key con la que llamas — quién es el dueño, qué workspace opera, con qué scopes y en qué entorno.

curl https://api.met.meteor.com.co/api/v1/me \
  -H "Authorization: Bearer $MET_API_KEY"

const yo = await met.me.retrieve();
console.log(yo.workspace?.id, yo.api_key.scopes, yo.livemode);

yo = met.me.retrieve()
print(yo["workspace"]["id"], yo["api_key"]["scopes"], yo["livemode"])

La respuesta, tal como llega por el cable. Toda respuesta correcta de la API viaja dentro de un sobre y el recurso está en data:

{
  "success": true,
  "data": {
    "object": "identity",
    "livemode": true,
    "api_key": {
      "id": "key_01HXYZ",
      "object": "api_key",
      "owner_type": "workspace",
      "env": "live",
      "scopes": ["items:read", "runs:execute", "runs:read"],
      "rate_limit_rpm": 120,
      "monthly_quota": null
    },
    "workspace": { "object": "workspace", "id": 7, "slug": "acme" },
    "partner": null
  }
}

Los SDK oficiales te entregan directamente el contenido de data, por eso en los ejemplos de arriba yo es el objeto de adentro. Si llamas con curl o con un cliente propio, lee .data. Un cliente generado del contrato ya lo sabe: el OpenAPI declara el sobre. Ver Errores e idempotencia.

Qué hacer con cada campo:

El endpoint nunca devuelve el secreto de la key, ni su prefijo, ni sus últimos caracteres, ni su longitud. Si perdiste la key, no la recuperas aquí: se crea una nueva en el panel.

GET /me pide el scope identity:read, que toda key tiene sin marcarlo: cualquier key válida puede preguntar quién es, aunque no traiga ningún otro scope. Hasta la versión 3.27.0 pedía runs:read.

Desde la terminal

met whoami imprime lo mismo, y con --save-workspace guarda en tu config local el workspace que el servidor resolvió, para que no tengas que pasar --workspace en cada comando:

met whoami
met whoami --save-workspace
met whoami --json

Si tu config local apunta a un workspace y la key opera otro, met whoami te lo dice: es el error que más tiempo hace perder, porque todo responde 200 y los datos simplemente no son los que esperabas.

Scopes

Una key solo puede hacer aquello para lo que tiene scope. Los scopes siguen el patrón dominio:acción, donde :write cubre crear, editar y borrar (no existe un :update aparte). Pide solo los que tu integración necesita: es más seguro.

Estas tablas salen del catálogo de scopes de la API y del contrato OpenAPI. La columna Endpoints dice cuántas operaciones REST piden ese scope hoy.

Un — en Endpoints significa que hoy ninguna operación REST pide ese scope. Sigue siendo válido: una key que ya lo tenga no deja de funcionar.

Ojo con conversions:read: sin endpoints REST, pero con eventos de webhook detrás. Para suscribir un endpoint a esos eventos, el scope hace falta.

rag:read, rag:write y sites:read ya no se ofrecen al emitir una key nueva ni al registrar una app OAuth. Las keys que los tengan guardados siguen igual; simplemente no habilitan ninguna llamada.

partner:community:read no habilitan ninguna llamada extra.

Ejecución de Mets

Datos

Conversaciones y canales

Integraciones y plataforma

Solo para keys de partner

Estos scopes no se pueden emitir en una key de workspace: el servidor lo re-verifica en cada request y responde 403. Ver la API de Partners.

Qué hace y qué no hace el modo de prueba

Una key met_test_ no puede ejercer scopes con efecto externo real: integrations:execute, images:generate, channels:send, conversions:write, channels:manage, workspaces:provision, workspaces:recharge, partner:billing:manage y snapshots:install responden 403 con test_mode_restricted. La restricción vale igual por REST y por el servidor MCP: una herramienta cuyo scope está restringido ni siquiera aparece en el catálogo que ve tu agente.

Eso, más el costo, es todo lo que el modo de prueba te separa de producción:

Solo dos cosas llevan la marca livemode y por eso se pueden distinguir después: los runs y los eventos. Todo lo demás que escribas con una key de prueba queda indistinguible de lo que escribió tu producción, así que tampoco hay forma de pedir "bórrame lo de prueba": esos registros se borran uno por uno, como cualquier otro.

La única excepción se limpia sola: un run sin conversation_id corre en una conversación efímera, y esas se purgan a los pocos días — vengan de una key de prueba o de una viva.

Para probar sin tocar tus datos, de menos a más trabajo:

1. Emite la key de prueba solo con scopes de lectura (más runs:execute si vas a ejecutar Mets). Es una decisión de una línea al crearla y cierra el problema entero: lo que no tiene scope de escritura no escribe.
2. Usa un workspace aparte para desarrollo y emite ahí la key de prueba. Es lo más cercano a un entorno separado que existe hoy, y es lo que puedes borrar entero cuando ya no lo necesites.
3. Mira primero la forma de las respuestas con la clave de demostración del portal: no pide registro, corre contra un negocio ficticio y es de solo lectura. Está en la portada, en *¿Prefieres no registrarte todavía?*.

Si una key intenta algo fuera de sus scopes, la API responde 403 con el código missing_scope (el campo param trae el scope faltante). No reintentes: pide al dueño de la key que amplíe los scopes.

Revocar

Una key revocada deja de funcionar en menos de 60 segundos. Revoca y rota keys ante cualquier sospecha de filtración, y usa keys distintas por entorno (una para test, otra para producción).

Apps que operan varios workspaces

Si construyes una app que deben conectar otros workspaces, no les pidas una API key. Registra una app OAuth en tu panel: Ajustes → Desarrolladores → Apps OAuth. El usuario ve los scopes y autoriza (o revoca) el acceso de tu app.

Sigue la guía de OAuth para apps de terceros: usa Authorization Code con PKCE S256, callbacks exactos y refresh tokens rotativos.