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.

By default, your Dedicated Gateway is restricted, it will only serve content pinned to your account. When you add an Access Control, your gateway becomes open and will be able to serve any content from IPFS, but only when requests meet your security requirements.

Restricted vs Open

When working with IPFS Gateways the behavior usually falls into two categories: Restricted or 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.

This check of whether or not a file is pinned or not using /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, not just pinned content. An example might be a public gateway like ipfs.io/ipfs/ which is open to everyone, but has heavy rate limiting. For Dedicated Gateways, you achieve this open state by adding Access Controls.

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
• IP Address
• Host Origin

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:

?pinataGatewayToken=PASTE_IN_ACCESS_TOKEN

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, ‘https://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!

Make sure you include the https:// protocol prefix in the URL and that there are no trailing slashes! To test localhost use the IP Access control with your public facing IP.

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:

html

<img
  src="https://pinata-media.mypinata.cloud/ipfs/CID"
  crossorigin="anonymous"
  alt="pinnie"
/>

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.