Claves de API

Cada integración programática con GCM se autentica con una clave de API. Zapier usa una. Tu backend personalizado usa una. Tu pipeline de data warehouse usa una. Esta página cubre cómo crearlas, limitar su alcance y retirarlas de forma segura.

Gestiona las claves en Integraciones → Zapier → API Keys. (A pesar de la URL, esto no es solo para Zapier — cualquier consumidor externo de la API de GCM usa claves de aquí.)

Crear una clave

Haz clic en Nueva clave. Dale una etiqueta que nombre para qué se usará la clave, no quién la creó:

• Zapier — Producción — para los Zaps.
• ETL de data warehouse — para tu trabajo de exportación nocturno.
• Sitio de directorio interno — para una intranet de personal que lista a los miembros.

Cuando hagas clic en crear, GCM muestra la clave en bruto una sola vez.

Cópiala de inmediato y guárdala en un gestor de secretos real — 1Password, AWS Secrets Manager, Doppler, Vault, la plataforma que prefieras. No la pegues en Slack, correo o una página de wiki.

WARNING

No almacenamos la clave en bruto. La base de datos solo guarda un hash, más un prefijo de 6 caracteres que puedes usar para identificar qué clave es cuál sin revelar el secreto. Si pierdes la clave en bruto, tu única opción es revocarla y volver a emitirla.

Formato de la clave

Las claves se ven como gcm_live_<32 caracteres aleatorios> o gcm_test_<32 caracteres aleatorios> según el entorno donde se acuñaron. El prefijo es visible en la lista de claves para que puedas saber de un vistazo qué clave es de producción vs staging sin ver nunca el secreto.

gcm_live_a1b2c3d4e5f6...
└─┬─┘└─┬─┘└──────┬──────┘
  │    │         └── 32 caracteres de entropía CSPRNG
  │    └── entorno
  └── producto (siempre `gcm`)

Alcances

Cada clave lleva una lista de alcances que limitan lo que puede hacer. El predeterminado para claves creadas a través de la interfaz de Zapier es read:* — acceso de solo lectura a cada recurso.

Alcance	Otorga
read:*	Listar y leer cada recurso público
read:members	Solo miembros
read:donations	Solo donaciones
write:members	Crear / actualizar miembros
write:donations	Registrar donaciones (para integraciones contables)
subscriptions:manage	Crear / eliminar suscripciones a webhooks
*	Acceso completo — equivalente a admin. Úsalo con moderación.

Los alcances son aplicados por el gateway de API, no por la lógica de aplicación — una clave read:* llamando a un endpoint de escritura recibe un 403 inmediatamente, nunca llega al RPC subyacente.

TIP

Comienza cada nueva integración con read:*. Solo amplía el alcance cuando hayas probado que el camino de lectura funciona y tengas un requisito real de escritura. Las claves con alcance excesivo son cómo los exploits se convierten en catástrofes.

Usar una clave

Envía la clave como token Bearer en cada solicitud:

curl https://api.geniuschurchmanager.com/v1/members \
  -H "Authorization: Bearer gcm_live_..."

Eso es todo. Sin baile de OAuth, sin firma por solicitud — solo el bearer. Combinado con HTTPS esto es suficiente para las integraciones para las que la API está diseñada.

Cada solicitud se registra con el prefijo de la clave, el endpoint alcanzado y el estado de respuesta. Puedes ver la marca de tiempo de último uso en la clave dentro de la interfaz de GCM — útil para detectar claves que no se han usado en meses (buenas candidatas para rotación o revocación).

Rotación

Debes rotar las claves de API:

• En un calendario — cada 12 meses como mínimo.
• Al salir personal — quien tuvo acceso a la clave en bruto no debería poder usarla después de irse.
• Ante sospecha de compromiso — si una clave aparece en un commit de Git, un mensaje de Slack o una captura de pantalla, trátala como comprometida.

Procedimiento de rotación:

1. Acuña una nueva clave con los mismos alcances.
2. Despliega la nueva clave al consumidor (conexión de Zapier, variable de entorno, gestor de secretos).
3. Verifica que el consumidor está usando la nueva clave observando que la marca de tiempo last_used avance.
4. Revoca la clave antigua.

GCM actualmente no admite ventanas de rotación superpuestas — la clave antigua funciona hasta que la revoques, y la nueva funciona desde el momento de su creación. Planifica tu transición.

Revocar

Pulsa el icono de papelera junto a cualquier clave. La clave queda marcada como revoked_at inmediatamente; la siguiente solicitud que la lleve recibe un 401.

WARNING

Revocar una clave en producción rompe instantáneamente a cualquier consumidor que la use. Los Zaps se detienen, tu trabajo de ETL lanza errores, tu sitio de directorio de intranet queda en blanco. Coordina la rotación, y luego revoca.

Las claves revocadas permanecen en la lista (en gris) para que puedas auditar cuándo fueron emitidas, cuándo se usaron por última vez y cuándo se retiraron. Para eliminar permanentemente una clave revocada antigua, contacta con soporte de plataforma — los auditores generalmente prefieren revocaciones a eliminaciones.

Auditar uso

La lista de claves muestra para cada clave:

• Marca de tiempo de creación.
• Marca de tiempo de último uso (continua — se actualiza en segundos tras una solicitud).
• Alcances.
• Marca de tiempo de revocación, si fue revocada.

Para auditoría más profunda — conteos por endpoint, distribución de códigos de respuesta, detección de abuso — los administradores de plataforma tienen acceso a la tabla api_request_log en exportaciones de BigQuery. Contáctanos si necesitas un corte específico.

Límites

Límite	Predeterminado
Claves por organización	20
Solicitudes por segundo por clave	60
Solicitudes por hora por clave	10,000
Solicitudes concurrentes por clave	20

Estos límites son deliberadamente generosos para integraciones legítimas y lo suficientemente estrictos como para hacer impráctica la enumeración por fuerza bruta. Si chocas con un límite, probablemente tienes un bucle descontrolado en algún sitio.

Lo que una clave de API no puede hacer

Por seguridad, las claves de API deliberadamente no pueden:

• Iniciar sesión interactivamente (sin sesión, sin acceso a la interfaz).
• Gestionar otras claves de API (solo la interfaz de Zapier puede, y solo los admins llegan a ella).
• Suplantar usuarios (el sistema JWT que controla la suplantación de admin de plataforma es independiente).
• Saltarse la seguridad a nivel de fila — cada consulta sigue limitada a current_org_id() derivado de la organización de la clave.

Estas son barandillas, no funciones: incluso una clave comprometida no puede escalar más allá de la organización que la posee.

Referencias cruzadas

• Integración con Zapier — el consumidor más común de estas claves.
• Webhooks salientes — usa las mismas claves para crear suscripciones.
• Autenticación de la API — referencia completa de la API para usar una clave.