전용 게이트웨이

Nirvana 플랜 사용자는 고유한 서브도메인에 프라이빗 IPFS 게이트웨이를 받습니다. 이 게이트웨이는 계정에 피닝된 파일만 제공하며, 다른 사용자나 퍼블릭 IPFS 네트워크의 CID는 해석하지 않습니다.

Gateways list page with multiple gateway cards

게이트웨이 URL

게이트웨이 URL은 게이트웨이 페이지에 표시되며, /user/profile 엔드포인트에서도 반환됩니다:

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

접근 모드

모드	동작
개방 (기본)	게이트웨이 URL + CID를 가진 누구나 파일에 접근할 수 있습니다. 토큰 불필요.
토큰 필수	요청에 `?token=gwt_...` 쿼리 매개변수 또는 `X-Gateway-Token` 헤더로 게이트웨이 토큰을 포함해야 합니다.

제한

Nirvana에는 월 50 GB 게이트웨이 대역폭이 포함됩니다
대역폭 한도에 도달하면 게이트웨이 요청은 다음 달까지 429를 반환합니다
저장 공간 사용량은 매월 1일에 초기화됩니다
계정에 피닝된 CID만 제공 — 다른 CID 요청은 403을 반환합니다

TIP

ipfs.ninja/ipfs/의 퍼블릭 게이트웨이는 모든 플랜에서 사용 가능하며 인증 없이 모든 CID를 제공합니다.

게이트웨이 설정

전용 게이트웨이의 접근 제어를 설정합니다.

Gateway detail page with access mode, token required, and IP whitelist settings

설정 업데이트

PUT /gateway-settings

매개변수	유형	필수	설명
`tokenRequired`	boolean	아니요	게이트웨이 토큰 요구 활성화/비활성화.
`ipWhitelist`	string[]	아니요	허용할 IP 주소 배열. 최대 100개. 빈 배열로 화이트리스트를 제거합니다.
`allowedOrigins`	string[]	아니요	브라우저 요청을 허용할 오리진 배열. 최대 100개. HTTPS 형식(예: `https://myapp.com`)을 사용해야 합니다. 빈 배열은 모든 오리진을 허용합니다.

예시

bash

# 토큰 필수 모드 활성화
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}'

# IP 화이트리스트 설정
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"]}'

# IP 화이트리스트 초기화 (모든 IP 허용)
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": []}'

# 특정 오리진으로 제한
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"]}'

# 오리진 제한 제거 (모든 오리진 허용)
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": []}'

오리진 제한

allowedOrigins가 설정되면, 목록에 있는 오리진의 브라우저 요청만 허용됩니다. 게이트웨이는 수신 요청의 Origin 및 Referer 헤더를 확인합니다.

목록이 비어 있으면 (기본), 모든 오리진이 허용됩니다.
오리진이 지정되면, 일치하지 않는 Origin 또는 Referer 헤더를 가진 요청은 403 응답으로 거부됩니다.
Origin 헤더가 없는 비브라우저 요청 (서버 측 요청이나 curl 등)은 제한 없이 통과합니다.

이것은 웹 애플리케이션에 게이트웨이 콘텐츠를 임베드하면서 다른 사이트가 파일을 핫링크하는 것을 방지하는 데 유용합니다.

게이트웨이 토큰

게이트웨이 토큰 (gwt_ 접두사)은 읽기 전용이며 프론트엔드 애플리케이션에 안전하게 임베드할 수 있습니다. API 키와 달리 게이트웨이 토큰은 전용 게이트웨이를 통해서만 파일에 접근할 수 있으며, 업로드, 삭제, 계정 관리는 할 수 없습니다.

기능	API 키 (`bws_`)	게이트웨이 토큰 (`gwt_`)
파일 업로드 / 삭제	예	아니요
파일 목록 / 메타데이터 조회	예	아니요
게이트웨이를 통한 파일 읽기	아니요	예
프론트엔드에 안전하게 임베드 가능	아니요	예

게이트웨이 토큰 생성

POST /gateway-tokens

매개변수	유형	필수	설명
`name`	string	아니요	토큰 라벨 (예: "Frontend"). 기본값은 "Default".

응답 `201 Created`

json

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

WARNING

전체 토큰은 생성 시 한 번만 반환됩니다. 안전하게 보관하세요.

게이트웨이 토큰 목록 조회

GET /gateway-tokens

json

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

게이트웨이 토큰 삭제

DELETE /gateway-tokens/:prefix

매개변수	유형	필수	설명
`prefix`	string	예	삭제할 토큰 접두사 (예: "gwt_a1b2c3d4").

게이트웨이 토큰 사용

게이트웨이에서 토큰 필수 모드가 활성화되면, 토큰을 쿼리 매개변수 또는 헤더로 전달하세요:

bash

# 쿼리 매개변수
curl "https://a1b2c3d4.gw.ipfs.ninja/ipfs/QmXk7VRz...?token=gwt_your_token"

# 또는 헤더
curl https://a1b2c3d4.gw.ipfs.ninja/ipfs/QmXk7VRz... \
  -H "X-Gateway-Token: gwt_your_token"

전용 게이트웨이 ​

게이트웨이 URL ​

접근 모드 ​

제한 ​

게이트웨이 설정 ​

설정 업데이트 ​

예시 ​

오리진 제한 ​

게이트웨이 토큰 ​

게이트웨이 토큰 생성 ​

응답 201 Created ​

게이트웨이 토큰 목록 조회 ​

게이트웨이 토큰 삭제 ​

게이트웨이 토큰 사용 ​