Gateway Access Controls
Pinata’s Dedicated Gateways make it possible to fetch and serve IPFS content quickly and reliably, however there can be security risks in exposing an open gateway to the world. That’s why Pinata has created Gateway Access Controls. These controls will allow you to further limit your gateway, making sure only your platform is using it. This is accomplished with Gateway Keys, IP Address Restrictions, and Host Origin Restrictions.
Restricted vs Open
When working with IPFS Gateways the behavior usually falls into two categories: Restricted and Open.
Restricted Gateway
Restricted means the gateway can only load content that is pinned to that user’s account. This is the default behavior for Pinata’s Dedicated Gateway, as it provides the maximum level of security. Any requests made to a CID outside the user’s account will be unauthorized.
/data/pinList in the Pinata API, which means recursive CIDs in folders are considered unauthorized. Instead, use the folder CID in the path of the gateway followed by the file name.Open Gateway
Open means the gateway can access any content on IPFS. An example might be a public gateway like gateway.pinata.cloud which are open to everyone, however might have rate limiting to keep them from crashing under heavy usage.
Why Access Controls?
If someone were to open their Dedicated Gateway without any permissions, anyone who found the domain could use it for themselves and abuse it, leaving the owner with a big bill of overages.
Because of this Pinata developed Gateway Access Controls to allow users to open their Gateways, but with restrictions that must be met first.
Access Controls
Pinata currently provides three primary methods for opening your gateway securely:
Gateway Keys
Adding a Gateway Key restriction means that content served through your gateway will only be served successfully if the key is present with the request. Importantly, content pinned to your account won’t be accessible through your gateway if you’ve implemented a gateway key restriction and fail to include that token in content requests.
To create a Gateway Key, click on the button that says “Request Key.”
When you create a key you will have the ability to preview the token by clicking the “eye” icon, or copy the token to your clipboard with the “copy” icon. At any point, you can delete a gateway key by clicking the “trash” icon.
Once you have the key, there are two ways you can use it in the gateway request.
Query Parameter
To use the query parameter method, simply add this to the end of a gateway request url:
Header
Another way to use the gateway key is in the request header. The Key Value would look like this:
| Key | Value |
|---|---|
| x-pinata-gateway-token | GATEWAY_KEY |
Please keep in mind that using the gateway key in the request header may not work in a client side application, so consider using IP Address restriction instead for those use cases.
IP Address
You can also restrict your gateway by IP Address. You can add up to 100 different IP addresses (individually). When you add this restriction, only content requested from an IP address that you’ve added will be served through your gateway.
To start, click “Set IP Address” on the right side of the menu.
You will get window asking for a valid IP Address which will allow any requests being made from the IP Address to go through!
Host Origin
With the Host Origin restriction, you can make sure your gateway can only be used on a specific domain (for example, ‘app.pinata.cloud’). To get started, click on “Add Host Origin.”
After that, you can add the domain you would like your gateway to be used from!
Keep in mind, if you are rendering content on the client side using Host Origins, you will need to include a crossorigin tag in your img, video, audio, link, or script elements. Here is an example with an img element in React:
For more info on crossorigin please read this article here!
Multiple Restrictions
You can add multiple Access Controls, and they will perform as an “OR” operator. This means that if you have Host Origins and a Gateway Key set, you can use either one for content to go through.