How to use scoped API keys with IPFS app development

When building applications, developers must protect the resources they expose within their application. API keys left open to the world can present a massive security risk. The ramifications of these keys being exposed could be anything from a financial loss (thanks to an unexpected bill) to an exposure of sensitive data. Developing apps in web3 is no different. While many applications in the web3 space try to build as much client-side as possible, there are still plenty of times where resources from other services are necessary. And in those cases, developers need to know how to protect themselves and their applications.

For developers that are building data and media intensive apps that need a decentralized and off-chain storage solution, IPFS is the best choice. However, building apps that leverage IPFS means developers have to either run their own IPFS infrastructure, make use of an IPFS Pinning Service, or both. When using an IPFS Pinning Service, it’s important to protect the API keys you use to access that service.

With Pinata, developers have a couple of options. They can use our starter template to build client/server apps with passthrough upload functionality. This allows developers to protect their Pinata API keys by only using them on the server. However, some developers truly do need to build client-side apps only. In that case, there is an alternative solution. It’s called Scoped Keys.

What is a Scoped Key?

A Scoped Key is a Pinata API key that allows for granular permissions. These permissions provide significantly more control when either handing out API keys to other members of your team or, as we mentioned earlier, building client-side applications in a safer way.

Scoped Keys have been a fundamental part of Pinata’s API for a few years now, and they give developers super powers that make building web3 apps easier. Let’s explore how you can create a Scoped Key and then we’ll dive into the practical use cases where such keys might come in handy.

How do you create a Scoped Key?

Creating a Scoped Key is as easy as logging into your Pinata account and navigating to the API Keys page. From there, just click New Key. A modal will appear on the screen that allows you to control what level of access the API key provides. Each of the scopes is mapped to API endpoints documented in our docs here.

You’ll also notice that you can limit the number of times an API key can be used. This is incredibly powerful because even if you share a key publicly that has the wrong scopes, you will limit the impact of its use.

Once you’ve created the key, you’ll be presented with an API key, an API secret, and a JWT. The JWT is a combination of the too and is the recommended way to interact with our API, but we support the legacy key and secret model still. Copy all of the key information and store it somewhere safe because it won’t be revealed again.

Depending on the scope of your key, you may now share the key with other developers on your team or even embed the key into your frontend application. With that in mind, let’s explore some practical applications of scoped keys.

What Are Scoped Keys Good For?

We’ve touched on some high-level examples of how a developer might use scoped keys, but let’s get into some details. Pinata has customers that are showcasing how to use scoped keys everyday, so let’s start there.

• Many NFT marketplaces that allow for minting on their web app will upload directly to Pinata from the frontend. They do this safely by making as server-side request to generate a time-limited and scoped API key for each upload. This ensures that the end users on the marketplace app are authenticated and will only receive a limited use key for the app to use on their behalf.
• Agencies and dev shops working with clients will often have their clients create a Pinata account. Since the agency only needs API keys to build their apps, the clients will often create keys with very specific scope to them and provide those keys to the agency for use in building the end product.
• A web application developer may need to load all of the previously uploaded files to present them in app. Because these files are already on the IPFS network and public, the developer may want to make the request straight from their frontend and avoid a server altogether. So, the developer would create a scoped key that limits its use to listing the pinned files on the account.
• A security-conscious developer may want to reduce the attack surface when using their API keys even if using them on the server. So, the developer might create API keys that are very strictly scoped. This aligns with the ideas behind the principle of least privilege.

Conclusion

Scoped keys provide such flexibility that there are many more examples out there in the wild that we have not heard of and have not yet been dreamt up. But no matter what, it’s all just IPFS at the end of the day. Pinata’s scoped keys just create a simpler and more secure way of getting files onto the network.

If you’re a developer building apps and using scoped keys, reach out! We’d love to hear how you’re using them.

Happy pinning!