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

TIP

O gateway público em ipfs.ninja/ipfs/ permanece disponível em todos os planos e serve qualquer CID sem autenticação.

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"