Gateways Dedicados

Los usuarios del plan Nirvana obtienen un gateway IPFS privado en un subdominio único. Este gateway solo sirve archivos fijados a tu cuenta — no resolvera CIDs de otros usuarios o de la red pública IPFS.

Tu URL de gateway

Tu URL de gateway se muestra en tu página de Gateway y es devuelta por el endpoint /user/profile:

https://<your-slug>.gw.ipfs.ninja/ipfs/<CID>

Modos de acceso

Modo	Comportamiento
Abierto (por defecto)	Cualquiera con tu URL de gateway + CID puede acceder a tus archivos. No se necesita token.
Token requerido	Las solicitudes deben incluir un token de gateway mediante el parámetro de consulta ?token=gwt_... o el encabezado X-Gateway-Token.

Límites

• 50 GB/mes de ancho de banda del gateway incluidos con Nirvana
• Cuando se alcanza el límite de ancho de banda, las solicitudes al gateway devuelven 429 hasta el mes siguiente
• El uso de almacenamiento se reinicia el primer día de cada mes calendario
• Solo sirve CIDs fijados a tu cuenta — las solicitudes para otros CIDs devuelven 403

Pasarela apex

La pasarela apex compartida en https://ipfs.ninja/ipfs/<CID> está disponible en todos los planes y no requiere autenticación, pero solo sirve CIDs que hayan sido subidos o fijados por un usuario de IPFS Ninja. Las solicitudes para cualquier otro CID devuelven HTTP 410 Gone.

Para un CID que no es tuyo, puedes (a) hacer POST /pin para fijarlo a tu cuenta y luego usar la URL apex, o (b) usar un gateway de terceros como https://ipfs.io/ipfs/<CID> o https://dweb.link/ipfs/<CID>.

Para incrustación de nivel producción (videos, visores NFT, sitios), el gateway dedicado mostrado arriba es el patrón recomendado — ofrece mayores límites de tasa, controles de acceso configurables y ancho de banda dedicado.

Configuración del Gateway

Configura los controles de acceso para tu gateway dedicado.

Actualizar Configuración

PUT /gateway-settings

Parámetro	Tipo	Requerido	Descripción
tokenRequired	boolean	No	Habilitar/deshabilitar el requisito de token del gateway.
ipWhitelist	string[]	No	Arreglo de direcciones IP permitidas. Máximo 100. Un arreglo vacío elimina la lista blanca.
allowedOrigins	string[]	No	Arreglo de origenes permitidos para solicitudes de navegador. Máximo 100. Deben usar formato HTTPS (ej. https://myapp.com). Un arreglo vacío permite todos los origenes.

Ejemplos

# Habilitar modo de token requerido
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"tokenRequired": true}'

# Configurar lista blanca de IPs
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ipWhitelist": ["203.0.113.1", "198.51.100.0"]}'

# Limpiar lista blanca de IPs (permitir todas las IPs)
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ipWhitelist": []}'

# Restringir a origenes especificos
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"allowedOrigins": ["https://myapp.com", "https://staging.myapp.com"]}'

# Eliminar restricciones de origen (permitir todos los origenes)
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"allowedOrigins": []}'

Restricciones de Origen

Cuando allowedOrigins está configurado, solo las solicitudes de navegador desde los origenes listados son permitidas. El gateway verifica los encabezados Origin y Referer en las solicitudes entrantes.

• Si la lista está vacía (por defecto), todos los origenes son permitidos.
• Si se especifican origenes, las solicitudes con un encabezado Origin o Referer que no coincida con ninguna entrada son rechazadas con una respuesta 403.
• Las solicitudes que no son de navegador que no incluyen un encabezado Origin (como fetches del lado del servidor o curl) pasan sin restricción.

Esto es util para incrustar contenido del gateway en tu aplicación web mientras se previene que otros sitios hagan hotlinking de tus archivos.

Tokens de Gateway

Los tokens de gateway (prefijo gwt_) son de solo lectura y seguros para incrustar en aplicaciones frontend. A diferencia de las claves API, un token de gateway solo puede acceder a archivos a través de tu gateway dedicado — no puede subir, eliminar ni gestionar tu cuenta.

Capacidad	Clave API (bws_)	Token de Gateway (gwt_)
Subir / eliminar archivos	Sí	No
Listar / obtener metadatos de archivos	Sí	No
Leer archivos vía gateway	No	Sí
Seguro para incrustar en frontend	No	Sí

Crear Token de Gateway

POST /gateway-tokens

Parámetro	Tipo	Requerido	Descripción
name	string	No	Etiqueta para el token (ej. "Frontend"). Por defecto "Default".

Respuesta 201 Created

{
  "token": "gwt_a1b2c3d4e5f6789012345678abcdef01",
  "tokenPrefix": "gwt_a1b2c3d4",
  "tokenName": "Frontend",
  "createdAt": 1711036800000
}

WARNING

El token completo solo se devuelve una vez al crearlo. Guardalo de forma segura.

Listar Tokens de Gateway

GET /gateway-tokens

[
  {
    "tokenPrefix": "gwt_a1b2c3d4",
    "tokenName": "Frontend",
    "createdAt": 1711036800000
  }
]

Eliminar Token de Gateway

DELETE /gateway-tokens/:prefix

Parámetro	Tipo	Requerido	Descripción
prefix	string	Sí	El prefijo del token a eliminar (ej. "gwt_a1b2c3d4").

Usar un token de gateway

Cuando tu gateway tiene habilitado el modo de token requerido, pasa el token como parámetro de consulta o encabezado:

# Parametro de consulta
curl "https://a1b2c3d4.gw.ipfs.ninja/ipfs/QmXk7VRz...?token=gwt_your_token"

# O encabezado
curl https://a1b2c3d4.gw.ipfs.ninja/ipfs/QmXk7VRz... \
  -H "X-Gateway-Token: gwt_your_token"