Cómo limitar una clave API a un solo proyecto

Una clave API se puede vincular a un único proyecto Cryptanio. Veamos un proceso de conciliación que necesita leer las facturas de una tienda sin acceder a los datos de los demás proyectos de la cuenta. Necesita una clave independiente: el proyecto define el ámbito de los datos, mientras que los permisos y las secciones API definen las operaciones permitidas.

Ni el nombre de la clave ni el número de proyecto en tu aplicación limitan el acceso por sí solos. Debes guardar la restricción en la política de la clave. El acceso corresponde a la API pública v1; la clave no es una contraseña para iniciar sesión en el panel.

1. Prepara el proyecto y los permisos

Necesitas permisos de propietario o administrador de la cuenta y un proyecto activo existente con el servicio «Pagos». Asegúrate primero de reconocer su nombre y finalidad: elegir el proyecto equivocado puede generar una clave válida con un ámbito inadecuado.

Abre «API claves». En el formulario «Crear API clave», rellena «Etiqueta», por ejemplo «Conciliación tienda». Un nombre independiente permite distinguir los procesos del servidor, pero la protección real se configura en los campos siguientes.

2. Elige el modo y un proyecto concreto

Para leer facturas reales, selecciona «Producción» en «Modo». La clave debe corresponder al modo de los datos que solicita tu servidor.

En «Proyecto», elige el proyecto necesario en lugar de «Todos los proyectos». El panel muestra una indicación sobre la restricción al servicio del proyecto seleccionado. La vinculación al proyecto y el acceso al servicio se aplican juntos: la clave no activa el servicio ni amplía por sí sola sus posibilidades.

3. Conserva solo la lectura de facturas

En «Acceso», selecciona «Lee sólo». En «API secciones», conserva «Invocaciones», el apartado de facturas, y desmarca el resto si el proceso no lo necesita. La conciliación habitual del estado de una factura no requiere administrar direcciones, webhooks ni simulación.

Si otro servidor debe crear facturas, necesitará «Lee y escriba» y la sección correspondiente. Dale una clave independiente con una finalidad clara, sin ampliar innecesariamente los permisos del proceso de conciliación. La escritura se aplica dentro de las secciones elegidas, no abre toda la API.

4. Configura las IP y el vencimiento

En «Directrices IP permitidas», introduce las IP públicas de salida de tu servidor o los rangos CIDR necesarios, uno por línea. Es la dirección desde la que la solicitud llega a la API, no la IP del comprador. Si utilizas alojamiento o un proxy, comprueba la dirección de salida real.

El campo vacío permite cualquier IP. Si el servidor usa varias direcciones de salida, tenlas en cuenta; de lo contrario, una clave válida puede no superar la comprobación. La restricción por IP complementa la selección del proyecto y las secciones, no las sustituye.

Configura «Expira» si lo necesitas. La fecha elegida es válida hasta el final de ese día en UTC. Ajústala al periodo de funcionamiento de la integración: que una clave haya vencido no significa que el cliente no haya pagado.

5. Crea la clave y guarda el secreto

Pulsa «Crear clave» y completa la confirmación de seguridad si el panel la solicita. Copia el secreto de la ventana mostrada y guárdalo en el servidor de conciliación. No lo incluyas en JavaScript del cliente, un enlace de pago, la correspondencia con el comprador ni registros públicos.

Después de cerrar la ventana, no cuentes con recuperar el secreto desde la lista: solo muestra una identificación abreviada. Comprueba «Límite», el proyecto, las secciones disponibles, el vencimiento y el estado. Si un desarrollador necesita acceso, compártelo mediante un almacenamiento seguro adecuado, no publiques la clave junto con la guía.

6. Comprueba los accesos permitidos y denegados

Desde un servidor con una IP permitida, lee una factura conocida de este proyecto. A continuación aparece un ejemplo de lectura del catálogo API; utiliza tu propio ID de factura y la clave creada:

#!/usr/bin/env bash
set -euo pipefail
: "${CRYPTANIO_RESOURCE_ID:?Set CRYPTANIO_RESOURCE_ID}"
: "${CRYPTANIO_API_KEY:?Set CRYPTANIO_API_KEY}"
urlencode() {
  local LC_ALL=C text="$1" char index
  for ((index=0; index<${#text}; index++)); do
    char="${text:index:1}"
    case "$char" in [a-zA-Z0-9.~_-]) printf '%s' "$char" ;; *) printf '%%%02X' "'$char" ;; esac
  done
}
response_file="$(mktemp)"
trap 'rm -f "$response_file"' EXIT
transfer_status=0
http_status="$(curl \
  --silent --show-error --max-time 30 --request GET \
  --header "Authorization: Bearer $CRYPTANIO_API_KEY" \
  --header 'Accept: application/json' \
  "https://api.cryptanio.com/v1/invoices/$(urlencode "$CRYPTANIO_RESOURCE_ID")" \
  --output "$response_file" --write-out '%{http_code}')" || transfer_status=$?
if [[ "$http_status" == 2?? ]]; then
  cat "$response_file"
  exit "$transfer_status"
fi
printf 'HTTP %s\n' "$http_status" >&2
cat "$response_file" >&2
exit 1

Descargar ejemplo

Después, comprueba el límite con una factura conocida de otro de tus proyectos: sus datos no deben devolverse. Los listados también deben limitarse al proyecto elegido. Esta clave no puede crear ni modificar facturas aunque «Invocaciones» esté habilitado. La conciliación posterior se explica en la guía para comprobar pagos mediante la API.

Si una solicitud falla, revisa el proyecto, el modo, la IP, el vencimiento y los permisos. No concluyas que falta el pago por un solo error de acceso ni sustituyas la clave restringida por una de toda la cuenta. El pago se evalúa según el estado de la factura.

Cómo ajustar el acceso más adelante

En una clave existente, pulsa «Acceso», cambia el proyecto, las secciones, las IP o el vencimiento y selecciona «Guardar acceso». El modo se elige al crear la clave. «Renovar» cambia el secreto y desactiva inmediatamente el anterior; «Revocar» impide seguir usando la clave. Prepara la actualización de los clientes del servidor antes del cambio para que la conciliación de pedidos no se detenga.