Obtén tu llave de API · Compense Docs

Todo el API Gateway se autentica con una llave de API que tu sistema envía en la cabecera X-API-Key. La llave identifica a tu entidad (el tenant): nunca envías un id de caja o de organización, y una llave jamás ve datos de otro tenant.

Cómo es una llave #

Empieza por cmp_ y se muestra una sola vez al emitirse. Guárdala en tu gestor de secretos (HashiCorp Vault, Azure Key Vault, Google Secret Manager, variables cifradas del CI…).
Se emite para un entorno: sandbox o prod. Una llave de sandbox recibe respuestas deterministas del motor simulado; una de producción llega al motor real (más en Entornos).
Lleva scopes (permisos de menor privilegio), un límite por minuto y, opcionalmente, una cuota mensual, una lista de IP permitidas y la firma de peticiones para operaciones de alto valor (Autenticación).

Cómo pedirla #

Entorno	Quién la emite	Para qué
Sandbox	Tu equipo la genera en el Portal de Desarrollador del panel de Compense, o la pide a su ejecutivo durante el onboarding.	Integrar y probar sin dinero real.
Producción	Compense, al cerrar el onboarding y las pruebas de tu integración.	Operar con datos y dinero reales.

Pide una llave por sistema (ERP, CRM, app de la fintech…) con solo los scopes que ese sistema usa: si una se filtra, la revocas sin afectar a las demás.

Scopes por módulo #

Módulo	Lectura	Escritura
Afiliados	`affiliates:read`	`affiliates:upsert`
Créditos	`credits:read`	`credits:submit`, `credits:decide`, `credits:disburse`
Subsidios y cuota monetaria	`subsidies:read`	`subsidies:submit`, `subsidies:decide`, `subsidies:disburse`
Billetera	`wallet:read`	`wallet:transfer` (P2P, Bre-B, entre bolsillos), `wallet:payments` (facturas), `wallet:topup` (recargas), `wallet:accounts`, `wallet:cards`, `wallet:fx`
Cartera	`loans:read`	`loans:collect` (recaudos, abonos, pago total)
PQRS	`pqrs:read`	`pqrs:submit`, `pqrs:manage` (responder, cambiar estado)
Salud — agenda	`appointments:read`	`appointments:write`
Salud — facturación	`health_billing:read`	`health_billing:collect`
Salud — vacunación	`vaccination:read`	—
Administrativo	`hr:read`, `payroll:read`, `accounting:read`	`hr:write`, `payroll:write`, `accounting:write`, `treasury:write`
Webhooks	`webhooks:read`	`webhooks:manage`
Transacciones	`transactions:read`	—

Además del scope, tu entidad debe tener contratado el módulo: si no, la llamada responde 403 aunque la llave tenga el scope. Para saber qué puede hacer una llave, llama a client.system.health() (quickstart): devuelve el tenant y sus scopes.

Guárdala bien #

La llave es un secreto de servidor

No la pongas en el código, en el repositorio, en una app móvil ni en un navegador. Los SDK son server-to-server: el de JavaScript corre en navegadores, pero nunca expongas ahí una llave.

Léela de una variable de entorno o de tu gestor de secretos:

import os
from compense_gateway import CompenseClient

client = CompenseClient(api_key=os.environ["COMPENSE_API_KEY"], environment="sandbox")

import { CompenseClient } from "@compense/sdk";

const client = new CompenseClient({ apiKey: process.env.COMPENSE_API_KEY!, environment: "sandbox" });

<?php
use Compense\Sdk\CompenseClient;

$client = new CompenseClient(apiKey: getenv('COMPENSE_API_KEY'), environment: 'sandbox');

// appsettings.json → "Compense": { "Environment": "Sandbox" }; la llave por variable de entorno:
// Compense__ApiKey=cmp_...
builder.Services.AddCompense(builder.Configuration.GetSection("Compense"));

client, err := compense.NewClient(os.Getenv("COMPENSE_API_KEY"),
	compense.WithEnvironment(compense.Sandbox))
if err != nil {
	log.Fatal(err)
}

export COMPENSE_API_KEY="cmp_..."   # nunca la escribas en un script versionado

Rotación y revocación #

Rota la llave cuando cambie el equipo que la conoce o si sospechas que se filtró: pide una nueva, despliégala y revoca la anterior. Mientras conviven, ambas funcionan.
Una llave revocada, suspendida o vencida responde 403. Una petición sin llave responde 401.
No confundas esta llave con el secreto de los webhooks (whsec_...), que firma las entregas que Compense te envía: se gestiona aparte (Rotar el secreto).