Pinata Authentication: API Keys & JWTs Explained (2026)

Authentication overview

Pinata provides decentralized storage and pinning services for the InterPlanetary File System (IPFS). To interact with the Pinata API and manage your content, authentication is required. This ensures that only authorized applications and users can upload, retrieve, and manage data associated with your account. Pinata's authentication mechanisms are designed to support a range of use cases, from server-side applications to client-side web applications, offering flexibility while maintaining security.

The primary method for authenticating with the Pinata REST API involves using a combination of an API Key and an API Secret. These credentials grant access to your account's resources and functions, such as pinning new content, listing existing pins, or managing dedicated gateways. For scenarios requiring more fine-grained control or time-limited access, such as serving content through Pinata's Submarine or dedicated gateways, JSON Web Tokens (JWTs) are utilized. JWTs offer a secure way to transmit information between parties as a JSON object, digitally signed to ensure authenticity and integrity, as described by the IETF RFC 7519 specification for JSON Web Tokens.

Understanding the appropriate authentication method for your specific integration is crucial for maintaining both functionality and security. Pinata's API documentation provides detailed guidance on how to implement each method effectively, including examples for common programming languages like JavaScript and cURL for direct HTTP requests. Proper management of these credentials, including secure storage and rotation, is a fundamental aspect of safeguarding your decentralized applications and data.

Supported authentication methods

Pinata supports two primary authentication methods tailored for different use cases and security requirements:

1. API Keys and API Secrets: This is the most common method for direct interaction with the Pinata REST API. It involves two components: an API Key (a public identifier) and an API Secret (a private credential). When making requests, these are typically sent in the request headers. This method is suitable for server-side applications, scripts, and development environments where the API Secret can be securely stored and managed.
2. JSON Web Tokens (JWTs): JWTs provide a more flexible and secure authentication mechanism, particularly useful for client-side applications, temporary access, or when integrating with Pinata's advanced features like Submarine and dedicated gateways. JWTs are generated using your API Key and API Secret, then signed. The signed token is sent in the Authorization header (e.g., Bearer <token>). JWTs can include claims such as expiration times, allowing for time-limited access tokens without exposing your long-lived API Secret. The official OAuth 2.0 Bearer Token usage specification outlines the standard for using such tokens.

Here's a comparison of when to use each method:

Getting your credentials

To begin using Pinata's services, you'll need to generate your authentication credentials from the Pinata dashboard. Both API Keys/Secrets and the necessary information to generate JWTs are managed here.

1. Create a Pinata Account: If you don't already have one, sign up for a Pinata account on their official website. The free Starter tier offers 1GB storage and 100GB bandwidth, sufficient for initial testing.
2. Navigate to API Keys Section: Once logged in, access your account dashboard. Look for a section typically labeled "API Keys" or "Developers" in the sidebar or menu. According to the Pinata documentation, this is where you manage your API credentials.
3. Generate New Key: Within the API Keys section, you will find an option to "New Key." Clicking this will prompt you to create a new set of credentials. You may be asked to provide a name for your key, which helps in organizing multiple keys for different projects or environments.
4. Record your API Key and API Secret: Upon generation, Pinata will display your API Key and API Secret. It is critical to record your API Secret immediately, as it will only be shown once for security reasons. If lost, you will need to generate a new key pair.
5. (Optional) Configure JWT Generation: For JWT authentication, you will use your API Key and API Secret to programmatically generate JWTs. There isn't a direct "generate JWT" button in the dashboard; rather, you use the API Key and Secret in your application logic to create signed tokens. Pinata's documentation provides code examples for this process, often leveraging libraries that implement the JSON Web Token standard.

It is recommended to generate separate API keys for different applications or environments (e.g., development, staging, production) to enhance security and simplify credential management. This practice allows for the revocation of a specific key without affecting other services.

Authenticated request example

This example demonstrates how to make an authenticated request to the Pinata API using an API Key and API Secret. The request pins a file to IPFS, which is a common operation. We'll use curl for a direct HTTP request and provide a JavaScript example using the fetch API.

cURL Example (API Key & API Secret)

This command pins a file located at a public URL to IPFS via Pinata. Replace YOUR_API_KEY and YOUR_API_SECRET with your actual credentials.

curl -X POST "https://api.pinata.cloud/pinning/pinByHash" \
  -H "Content-Type: application/json" \
  -H "pinata_api_key: YOUR_API_KEY" \
  -H "pinata_secret_api_key: YOUR_API_SECRET" \
  --data '{"hashToPin":"QmZq5W1Gv4q1q1P1p1q1R1s1t1u1v1w1x1y1z1"}'

This example uses the pinByHash endpoint. If you are uploading a file directly, the endpoint would be /pinning/pinFileToIPFS and would require a multipart/form-data body.

JavaScript Example (API Key & API Secret)

This JavaScript example demonstrates uploading a file to Pinata using the pinFileToIPFS endpoint. This requires a FormData object to send the file.

const fs = require('fs');
const axios = require('axios');
const FormData = require('form-data');

const pinataApiKey = process.env.PINATA_API_KEY;
const pinataSecretApiKey = process.env.PINATA_SECRET_API_KEY;

const pinFileToIPFS = async () => {
    const url = `https://api.pinata.cloud/pinning/pinFileToIPFS`;

    let data = new FormData();
    data.append('file', fs.createReadStream('./your-file.jpg')); // Replace with your file path

    const pinataOptions = JSON.stringify({
        cidVersion: 0,
        wrapWithDirectory: false
    });
    data.append('pinataOptions', pinataOptions);

    const pinataMetadata = JSON.stringify({
        name: 'My Awesome File',
        keyvalues: {
            company: 'Pinata',
            product: 'Test'
        }
    });
    data.append('pinataMetadata', pinataMetadata);

    try {
        const res = await axios.post(url, data, {
            maxBodyLength: 'Infinity', // This is important to prevent errors with large files
            headers: {
                'Content-Type': `multipart/form-data; boundary=${data._boundary}`,
                'pinata_api_key': pinataApiKey,
                'pinata_secret_api_key': pinataSecretApiKey
            }
        });
        console.log(res.data);
    } catch (error) {
        console.error('Error pinning file to IPFS:', error);
    }
};

pinFileToIPFS();

JavaScript Example (JWT authentication)

For JWT authentication, you would first generate the JWT using your API Key and Secret, and then include it in the Authorization header:

const JWT_TOKEN = "YOUR_GENERATED_JWT_TOKEN"; // This token would be generated on your backend

const fetchWithJWT = async () => {
    const url = `https://api.pinata.cloud/data/testAuthentication`; // An example endpoint
    try {
        const res = await fetch(url, {
            method: 'GET',
            headers: {
                'Authorization': `Bearer ${JWT_TOKEN}`
            }
        });
        const data = await res.json();
        console.log(data);
    } catch (error) {
        console.error('Error with JWT authentication:', error);
    }
};

fetchWithJWT();

The process of generating a JWT typically occurs on a secure backend server to prevent exposure of your API Secret. Libraries like jsonwebtoken in Node.js can be used for this purpose.

Security best practices

Securing your Pinata credentials is vital to protect your IPFS content and account from unauthorized access. Adhere to these best practices:

1. Do Not Hardcode Credentials: Never embed your API Key or API Secret directly into your application's source code, especially for client-side applications. This exposes your credentials to anyone who can view your code. Instead, store them in environment variables, configuration files that are not committed to version control, or secure secret management services.
2. Use Environment Variables: For server-side applications and scripts, store your pinata_api_key and pinata_secret_api_key as environment variables. This keeps them out of your codebase and allows for easy rotation without code changes. Most deployment platforms provide mechanisms for managing environment variables securely.
3. Backend for Client-Side Operations: If your application is client-side (e.g., a web application running in a browser), all interactions requiring your API Secret (like JWT generation or direct API calls with API keys) should be routed through a secure backend server. The client application calls your backend, which then authenticates with Pinata. This prevents your sensitive API Secret from ever being exposed in the user's browser.
4. Principle of Least Privilege: Generate separate API keys for different applications, projects, or environments. If a key is compromised, you can revoke it without affecting other parts of your infrastructure. Pinata's dashboard allows you to manage multiple keys.
5. Rotate API Keys Regularly: Periodically generate new API keys and replace the old ones. This minimizes the window of opportunity for a compromised key to be exploited. A common practice is to rotate keys every 90 days or as per your organization's security policy.
6. Monitor API Usage: Regularly check your Pinata dashboard for unusual activity or excessive API calls that might indicate a compromised key.
7. Securely Handle JWTs: If using JWTs, ensure they are generated securely on your backend. Set appropriate expiration times (exp claim) to limit the duration a token is valid. Transmit JWTs over HTTPS to prevent interception and store them securely on the client-side (e.g., HTTP-only cookies, local storage with caution). Remember that a JWT is signed, not encrypted, meaning its contents are readable but not alterable without invalidating the signature.
8. Implement Rate Limiting and Error Handling: Implement rate limiting on your application to prevent abuse of your Pinata API access, even if a key is compromised. Robust error handling can also help detect and respond to unauthorized access attempts.
9. Keep Dependencies Updated: Ensure that any libraries or SDKs used for authentication (e.g., JWT libraries) are kept up-to-date to benefit from the latest security patches.

By following these best practices, developers can significantly enhance the security posture of their applications interacting with the Pinata platform, safeguarding their decentralized content and user data.