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.

Hoy GET /me requiere el scope runs:read. Si tu key no lo tiene, responde 403 missing_scope — la key es válida, simplemente no alcanza este endpoint.

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.

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.

Restringidos en modo de prueba

Una key met_test_ no puede ejercer scopes con efecto externo real: integrations:execute, channels:send, conversions:write, workspaces:provision, workspaces:recharge, partner:billing:manage y snapshots:install responden 403 con test_mode_restricted. El resto de la superficie funciona igual, incluido el CRUD autorizado: items:write, por ejemplo, modifica ítems reales del workspace.

El modo test separa la atribución de ejecución (livemode: false) y el costo de los runs; no crea una copia ni revierte datos. Para pruebas descartables, usa un workspace dedicado y una key de test de ese workspace.

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.