Get your API key · Compense Docs

The entire API Gateway authenticates with an API key that your system sends in the X-API-Key header. The key identifies your entity (the tenant): you never send the id of a family compensation fund (caja de compensación) or of an organization, and a key never sees another tenant’s data.

What a key looks like #

It starts with cmp_ and is shown only once when issued. Store it in your secrets manager (HashiCorp Vault, Azure Key Vault, Google Secret Manager, encrypted CI variables…).
It’s issued for an environment: sandbox or prod. A sandbox key gets deterministic responses from the simulated engine; a production key reaches the real engine (more in Environments).
It carries scopes (least-privilege permissions), a per-minute limit and, optionally, a monthly quota, an IP allowlist and request signing for high-value operations (Authentication).

How to request one #

Environment	Who issues it	What for
Sandbox	Your team generates it in the Developer Portal of the Compense dashboard, or requests it from your account executive during onboarding.	Integrating and testing without real money.
Production	Compense, once onboarding and your integration testing are complete.	Operating with real data and money.

Request one key per system (ERP, CRM, fintech app…) with only the scopes that system uses: if one leaks, you revoke it without affecting the others.

Scopes by module #

Module	Read	Write
Affiliates	`affiliates:read`	`affiliates:upsert`
Credits	`credits:read`	`credits:submit`, `credits:decide`, `credits:disburse`
Subsidies and monetary allowance	`subsidies:read`	`subsidies:submit`, `subsidies:decide`, `subsidies:disburse`
Wallet	`wallet:read`	`wallet:transfer` (P2P, Bre-B, between pockets), `wallet:payments` (bills), `wallet:topup` (top-ups), `wallet:accounts`, `wallet:cards`, `wallet:fx`
Loans	`loans:read`	`loans:collect` (collections, partial payments, payoff)
PQRS	`pqrs:read`	`pqrs:submit`, `pqrs:manage` (respond, change status)
Health — scheduling	`appointments:read`	`appointments:write`
Health — billing	`health_billing:read`	`health_billing:collect`
Health — vaccination	`vaccination:read`	—
Administrative	`hr:read`, `payroll:read`, `accounting:read`	`hr:write`, `payroll:write`, `accounting:write`, `treasury:write`
Webhooks	`webhooks:read`	`webhooks:manage`
Transactions	`transactions:read`	—

Besides the scope, your entity must have the module contracted: otherwise the call responds 403 even if the key has the scope. To find out what a key can do, call client.system.health() (quickstart): it returns the tenant and its scopes.

Store it safely #

The key is a server-side secret

Don’t put it in code, in the repository, in a mobile app or in a browser. The SDKs are server-to-server: the JavaScript one runs in browsers, but never expose a key there.

Read it from an environment variable or from your secrets manager:

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" }; the key via environment variable:
// 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_..."   # never write it in a versioned script

Rotation and revocation #

Rotate the key when the team that knows it changes or if you suspect it leaked: request a new one, deploy it and revoke the old one. While they coexist, both work.
A revoked, suspended or expired key responds 403. A request without a key responds 401.
Don’t confuse this key with the webhook secret (whsec_...), which signs the deliveries Compense sends you: it’s managed separately (Rotate the secret).