Llaves de API y autenticación

Llaves secretas por comercio (MID) en Authorization: Bearer, scopes, rotación y revocación.

La API pública se autentica con una llave secreta por comercio (MID). El MID sale de la llave, así que no va en la URL. Envía la llave en cada petición, siempre sobre HTTPS:

Cabecera
Authorization: Bearer $CLOBEPAY_API_KEY

También se acepta X-API-Key: <llave>. Si envías las dos cabeceras con valores distintos, la API responde 400 ambiguous_credentials.

cURL · Comprobar tu llave
curl "$CLOBEPAY_API_BASE/me" \
  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Respuesta esperada: HTTP 200

Formato

sk_<entorno>_<key_id>.<secreto>, donde el entorno es test o live. La llave completa se muestra una sola vez al crearla; después solo verás el prefijo, los últimos 4 caracteres y sus metadatos (etiqueta, scopes, último uso).

Scopes

Cada llave tiene permisos por recurso. Una llave creada sin scopes explícitos tiene todos excepto payouts:write: para crear transferencias por API debes incluirlo al crear la llave. Sin el scope necesario la API responde 403 insufficient_scope.

Scopes de las llaves
ScopeRecurso
payment_links:read / :writeLinks de pago
payins:readPayins
deposit_accounts:read / :writeCuentas de depósito
payouts:read / :writeTransferencias, beneficiarios y billeteras
balance:readSaldo
verification:read / :writeKYC/KYB
webhooks:read / :writeEndpoints y entregas de webhooks

Crear, rotar y revocar

  • Las crea el dueño del comercio desde el panel. El comercio debe estar operativo.
  • Máximo 5 llaves activas por MID y entorno.
  • Rotación sin caída: crea una llave nueva, despliégala y programa la expiración de la anterior (hasta 168 horas) o revócala.
  • La revocación tiene efecto inmediato.

Límites de peticiones

Valores iniciales por llave: ráfaga de 50 peticiones por segundo y 1,000 por minuto; crear transferencias, 10 por minuto. Al excederlos la API responde 429 con Retry-After y las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset.

Errores de autenticación

Errores de autenticación
HTTPCódigoCausa
401missing_credentialsNo enviaste llave.
401invalid_api_keyLa llave no existe o no coincide.
401api_key_revokedLa llave fue revocada.
401api_key_expiredLa llave expiró (por ejemplo, tras una rotación).
401api_key_wrong_environmentLlave de prueba en producción o al revés.
403insufficient_scopeLa llave no tiene el scope de la operación.
403merchant_not_operationalEl comercio no está operativo.

Un recurso de otro comercio responde 404, no 403, para no confirmar que existe.

Buenas prácticas

  • Guarda la llave solo en el servidor (variables de entorno o gestor de secretos).
  • Nunca la pongas en código de navegador, apps móviles ni repositorios.
  • No registres la cabecera Authorization en tus logs.
  • Una llave por servicio y entorno; rótala si sospechas una filtración.