Gateways Dedicados

Usuarios do plano Nirvana recebem um gateway IPFS privado em um subdominio único. Este gateway serve apenas arquivos fixados na sua conta — não resolvera CIDs de outros usuarios ou da rede IPFS pública.

Sua URL de gateway

Sua URL de gateway é exibidaexibida na sua página de Gateway e retornada pelo endpoint /user/profile:

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

Modos de acesso

Modo	Comportamento
Aberto (padrão)	Qualquer pessoa com sua URL de gateway + CID pode acessar seus arquivos. Nenhum token necessário.
Token obrigatório	As requisições devem incluir um token de gateway pelo parâmetro de consulta ?token=gwt_... ou cabeçalho X-Gateway-Token.

Limites

• 50 GB/mes de largura de banda do gateway incluidos com o Nirvana
• Quando o limite de largura de banda é atingatingido, as requisições do gateway retornam 429 até o próximo mes
• O uso de armazenamento reseta no primeiro dia de cada mes
• Serve apenas CIDs fixados na sua conta — requisições para outros CIDs retornam 403

Gateway apex

O gateway apex compartilhado em https://ipfs.ninja/ipfs/<CID> está disponível em todos os planos e não requer autenticação, mas serve apenas CIDs que tenham sido enviados ou fixados por um usuário do IPFS Ninja. Solicitações para qualquer outro CID retornam HTTP 410 Gone.

Para um CID que não é seu, você pode (a) fazer POST /pin para fixá-lo à sua conta e usar a URL apex, ou (b) usar um gateway de terceiros como https://ipfs.io/ipfs/<CID> ou https://dweb.link/ipfs/<CID>.

Para incorporação em produção (vídeos, visualizadores NFT, sites), o gateway dedicado acima é o padrão recomendado — oferece limites de taxa maiores, controles de acesso configuráveis e largura de banda dedicada.

Configurações do Gateway

Configure os controles de acesso para seu gateway dedicado.

Atualizar Configurações

PUT /gateway-settings

Parâmetro	Tipo	Obrigatório	Descrição
tokenRequired	boolean	Não	Habilitar/desabilitar o requisito de token do gateway.
ipWhitelist	string[]	Não	Array de endereços IP permitidos. Máximo 100. Um array vazio remove a lista de permissões.
allowedOrigins	string[]	Não	Array de origens permitidas para requisições de navegador. Máximo 100. Devem usar formato HTTPS (ex.: https://myapp.com). Um array vazio permite todas as origens.

Exemplos

# Habilitar modo de token obrigatorio
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 de IPs permitidos
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"]}'

# Limpar lista de IPs permitidos (permitir todos os 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 origens especificas
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"]}'

# Remover restricoes de origem (permitir todas as origens)
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": []}'

Restrições de Origem

Quando allowedOrigins está configurado, apenas requisições de navegador das origens listadas são permitidas. O gateway verifica os cabeçalhos Origin e Referer nas requisições recebidas.

• Se a lista estiver vazia (padrão), todas as origens são permitidas.
• Se origens forem especificadas, requisições com um cabeçalho Origin ou Referer que não corresponda a nenhuma entrada são rejeitadas com uma resposta 403.
• Requisições que não são de navegador que não incluem um cabeçalho Origin (como fetches do lado do servidor ou curl) passam sem restrição.

Isso é útil para incorporar conteúdo do gateway na sua aplicação web enquanto impede que outros sites facam hotlinking dos seus arquivos.

Tokens de Gateway

Os tokens de gateway (prefixo gwt_) são somente leitura e seguros para incorporar em aplicações frontend. Diferente das chaves API, um token de gateway só pode acessar arquivos pelo seu gateway dedicado — não pode fazer upload, excluir ou gerenciar sua conta.

Capacidade	Chave API (bws_)	Token de Gateway (gwt_)
Upload / exclusao de arquivos	Sim	Não
Listar / obter metadados de arquivos	Sim	Não
Ler arquivos via gateway	Não	Sim
Seguro para incorporar em frontend	Não	Sim

Criar Token de Gateway

POST /gateway-tokens

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Não	Rótulo para o token (ex.: "Frontend"). Padrão: "Default".

Resposta 201 Created

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

WARNING

O token completo só é retornretornado uma vez na criacao. Armazene-o com segurança.

Listar Tokens de Gateway

GET /gateway-tokens

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

Excluir Token de Gateway

DELETE /gateway-tokens/:prefix

Parâmetro	Tipo	Obrigatório	Descrição
prefix	string	Sim	O prefixo do token a excluir (ex.: "gwt_a1b2c3d4").

Usando um token de gateway

Quando seu gateway tem o modo de token obrigatório habilitado, passe o token como parâmetro de consulta ou cabeçalho:

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

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