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:
Authorization: Bearer $CLOBEPAY_API_KEYTambién se acepta X-API-Key: <llave>. Si envías las dos cabeceras con valores distintos, la API responde 400 ambiguous_credentials.
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.
| Scope | Recurso |
|---|---|
payment_links:read / :write | Links de pago |
payins:read | Payins |
deposit_accounts:read / :write | Cuentas de depósito |
payouts:read / :write | Transferencias, beneficiarios y billeteras |
balance:read | Saldo |
verification:read / :write | KYC/KYB |
webhooks:read / :write | Endpoints 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
| HTTP | Código | Causa |
|---|---|---|
| 401 | missing_credentials | No enviaste llave. |
| 401 | invalid_api_key | La llave no existe o no coincide. |
| 401 | api_key_revoked | La llave fue revocada. |
| 401 | api_key_expired | La llave expiró (por ejemplo, tras una rotación). |
| 401 | api_key_wrong_environment | Llave de prueba en producción o al revés. |
| 403 | insufficient_scope | La llave no tiene el scope de la operación. |
| 403 | merchant_not_operational | El 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
Authorizationen tus logs. - Una llave por servicio y entorno; rótala si sospechas una filtración.