전용 게이트웨이

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

게이트웨이 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을 반환합니다

apex 게이트웨이

https://ipfs.ninja/ipfs/<CID>의 공유 apex 게이트웨이는 모든 요금제에서 사용할 수 있으며 인증이 필요하지 않지만, IPFS Ninja 사용자가 업로드하거나 고정한 CID만 제공합니다. 다른 CID에 대한 요청은 HTTP 410 Gone을 반환합니다.

소유하지 않은 CID의 경우 (a) POST /pin으로 계정에 고정한 후 apex URL을 사용하거나, (b) https://ipfs.io/ipfs/<CID> 또는 https://dweb.link/ipfs/<CID> 같은 타사 게이트웨이를 사용할 수 있습니다.

프로덕션급 임베딩(동영상, NFT 뷰어, 사이트)의 경우 위의 전용 게이트웨이가 권장 패턴입니다 — 더 높은 속도 제한, 구성 가능한 액세스 제어 및 전용 대역폭을 제공합니다.

게이트웨이 설정

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

설정 업데이트

PUT /gateway-settings

매개변수	유형	필수	설명
tokenRequired	boolean	아니요	게이트웨이 토큰 요구 활성화/비활성화.
ipWhitelist	string[]	아니요	허용할 IP 주소 배열. 최대 100개. 빈 배열로 화이트리스트를 제거합니다.
allowedOrigins	string[]	아니요	브라우저 요청을 허용할 오리진 배열. 최대 100개. HTTPS 형식(예: https://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 '{"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

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

WARNING

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

게이트웨이 토큰 목록 조회

GET /gateway-tokens

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

게이트웨이 토큰 삭제

DELETE /gateway-tokens/:prefix

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

게이트웨이 토큰 사용

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

# 쿼리 매개변수
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"