To manage your IPFS data, you need to register your account and set up your project.

After the registration, you will be redirected to the settings page, where you will find your project's credentials to authenticate your API calls with: PROJECT_ID and PROJECT_SECRET.

curl -X POST -F file=@myfile \
-u "PROJECT_ID:PROJECT_SECRET" \
"https://ipfs.infura.io:5001/api/v0/add"

> {
      "Name":"ipfs_file_docs_getting_started_demo.txt",
      "Hash":"QmeGAVddnBSnKc1DLE7DLV9uuTqo5F7QbaveTjr45JUdQn",
      "Size":"44"
  }

When you add a file using the /api/v0/add endpoint, the file is automatically pinned, and it isn't necessary to pin again.

Do you want to ensure that some file on IPFS is always available? Pin it to your PROJECT. Infura will copy it, store it, and keep it online on the IPFS P2P network.

curl -X POST -u "PROJECT_ID:PROJECT_SECRET" \
"https://ipfs.infura.io:5001/api/v0/pin/add?arg=QmeGAVddnBSnKc1DLE7DLV9uuTqo5F7QbaveTjr45JUdQn"

A pinned file will appear in your project's dashboard explorer and can be un-pinned at any time either using the unpin button in the UI or via the following /pin/rm endpoint.

curl -X POST -u "PROJECT_ID:PROJECT_SECRET" \
"https://ipfs.infura.io:5001/api/v0/pin/rm?arg=QmeGAVddnBSnKc1DLE7DLV9uuTqo5F7QbaveTjr45JUdQn"

curl -X POST -u "PROJECT_ID:PROJECT_SECRET" \
"https://ipfs.infura.io:5001/api/v0/cat?arg=QmeGAVddnBSnKc1DLE7DLV9uuTqo5F7QbaveTjr45JUdQn"

> Infura IPFS - Getting started demo.

The Infura IPFS API is compatible with the official IPFS API. Same HTTP endpoints, flags, arguments. The only additional step you must take when interacting with the Infura API is to configure the correct Basic Authentication header.

Authorization: Basic <base64(USERNAME:PASSWORD)>

The credentials are a base64-encoded string combination of a username and password, where the username is your PROJECT_ID and password is the PROJECT_SECRET. You will find your credentials in your project's settings page after you register your Infura account and create a new project.

Below are some examples of how to execute an authenticated Infura IPFS API call.

cURL generates the auth header and encodes your credentials behind the scenes. All you have to do is specify the -u flag.

curl -X POST -F file=@myfile -u "PROJECT_ID:PROJECT_SECRET" "https://ipfs.infura.io:5001/api/v0/add"

If you already have an existing project making IPFS API calls developed in JS, wrap your calls and decorate them with a new Infura Authorization header. Everything else stays the same, as the Infura API is fully compatible with IPFS.

xhr.setRequestHeader("Authorization", "Basic " + btoa(PROJECT_ID + ":" + PROJECT_SECRET));

Here is a complete example you can copy-paste and execute using NodeJS. Change the projectId, projectSecret to match yours.

const https = require('https')

const projectId = '1qmt...XXX'
const projectSecret = 'c920...XXX'

const options = {
  host: 'ipfs.infura.io',
  port: 5001,
  path: '/api/v0/pin/add?arg=QmeGAVddnBSnKc1DLE7DLV9uuTqo5F7QbaveTjr45JUdQn',
  method: 'POST',
  auth: projectId + ':' + projectSecret
}

let req = https.request(options, (res) => {
  let body = ''
  res.on('data', function (chunk) {
    body += chunk
  })
  res.on('end', function () {
    console.log(body)
  })
})
req.end()

You can also use the official js-ipfs/ipfs-http-client library!

const ipfsClient = require('ipfs-http-client')

const projectId = '1qmt...XXX'
const projectSecret = 'c920...XXX'
const auth =
  'Basic ' + Buffer.from(projectId + ':' + projectSecret).toString('base64')

const client = ipfsClient({
  host: 'ipfs.infura.io',
  port: 5001,
  protocol: 'https',
  headers: {
    authorization: auth
  }
})

client.pin.add('QmeGAVddnBSnKc1DLE7DLV9uuTqo5F7QbaveTjr45JUdQn').then((res) => {
  console.log(res)
})

Backend developers interacting with IPFS API via the ipfs/go-ipfs-api library can include the Infura auth header by implementing the following http.RoundTripper wrapper.

package main

import (
    "fmt"
    "net/http"
    "os"
    "strings"

    ipfsApi "github.com/ipfs/go-ipfs-api" // v0.2.0
)

func main() {
    projectId := "1qmt...XXX"
    projectSecret := "c920...XXX"

    shell := ipfsApi.NewShellWithClient("https://ipfs.infura.io:5001", NewClient(projectId, projectSecret))
    cid, err := shell.Add(strings.NewReader("Infura IPFS - Getting started demo."))
    if err != nil {
        fmt.Println(err)
        os.Exit(1)
    }

    fmt.Printf("Data successfully stored in IPFS: %v\n", cid)
}

// NewClient creates an http.Client that automatically perform basic auth on each request.
func NewClient(projectId, projectSecret string) *http.Client {
    return &http.Client{
        Transport: authTransport{
            RoundTripper:  http.DefaultTransport,
            ProjectId:     projectId,
            ProjectSecret: projectSecret,
        },
    }
}

// authTransport decorates each request with a basic auth header.
type authTransport struct {
    http.RoundTripper
    ProjectId     string
    ProjectSecret string
}

func (t authTransport) RoundTrip(r *http.Request) (*http.Response, error) {
    r.SetBasicAuth(t.ProjectId, t.ProjectSecret)
    return t.RoundTripper.RoundTrip(r)
}

For developers using the newer ipfs/go-ipfs-http-client library, here is a full example of how to authenticate your requests.

package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "net/http"
    "os"
    "strings"

    ipfsFiles "github.com/ipfs/go-ipfs-files" // v0.0.8
    ipfsApi "github.com/ipfs/go-ipfs-http-client" // v0.1.0
)

func main() {
    projectId := "1qmt...XXX"
    projectSecret := "c920...XXX"

    httpClient := &http.Client{}
    httpApi, err := ipfsApi.NewURLApiWithClient("https://ipfs.infura.io:5001", httpClient)
    if err != nil {
        fmt.Println(err)
        os.Exit(1)
    }
    httpApi.Headers.Add("Authorization", "Basic " + basicAuth(projectId, projectSecret))

    content := strings.NewReader("Infura IPFS - Getting started demo.")
    p, err := httpApi.Unixfs().Add(context.Background(), ipfsFiles.NewReaderFile(content))
    if err != nil {
        fmt.Println(err)
        os.Exit(1)
    }

    fmt.Printf("Data successfully stored in IPFS: %v\n", p.Cid().String())
}

func basicAuth(projectId, projectSecret string) string {
    auth := projectId + ":" + projectSecret
    return base64.StdEncoding.EncodeToString([]byte(auth))
}

Security settings for your project are available in the dashboard by clicking "Settings" and then the "Security" tab.

If you are sending API requests from a web browser or other client-side application which does not have the ability to secure your Project Secret, allowlisting can be used to prevent a third party from using your Project ID on another website.

Infura's IPFS API allows you to restrict requests by IP address, HTTP User-Agent, and HTTP Origin.

• If a project has no allowlists enabled, any request will be accepted.
• As soon as any allowlist entries are added, all requests must pass each allowlist type.
• A maximum of 30 allowlist entries per type are allowed per project.
• Each allowlist type is "AND"ed together
• Multiple entries of the same type are "OR"ed.

Example

Scenario: Alice allowlisted the User-Agent of her mobile application and the Origin where her web app is hosted.

User-Agent Allowlist entry: com.example.aliceapp

Origin Allowlist Entry: aliceapp.example.com

Result: Both Alice's mobile app AND her website are allowed to use the same Project ID. If Alice created a new website under aliceawesomeapp.example.com, she would need to add this new Origin to the allowlist to allow the Project ID to function on the new site. Alternatively, she could set a single Origin in the allowlist entry to use a wildcard subdomain pattern such as *.example.com which would allow all requests matching the pattern yet reject requests from origins not matching *.example.com.

In order to prevent unauthorized applications or users from using your project to make requests, you can specify the IP addresses from which requests can be made. You can either specify a single IP address (e.g. 1.1.1.1) or a range of IP addresses (e.g 1.1.1.1-2.2.2.2). If there are entries in this allowlist, then requests from IP addresses that do not match at least one of them will be rejected.

Example

Allowlist entry: 1.1.1.1

Request's IP address: 1.1.1.2

Result: Request is rejected, since it does not originate from the allowed IP address.

Example

Allowlist entry: 1.1.1.1-2.2.2.2

Request's IP address: 1.1.1.2

Result: Request is allowed, since it originates from an IP address in the allowed range.

If you are distributing a product which embeds an API key and you have the ability to set a custom User-Agent (e.g. an Electron app, iOS or Android app), we recommend adding the known User-Agent to your allowlist.

When a User-Agent is added to the allowlist, any API requests which originate from other platforms will be rejected.

Matching Behavior

The User-Agent allowlist utilizes partial string matching. If the allowlisted string is present in the request's full User-Agent, it is registered as a match.

Example

Allowlist entry: com.example.dapp

Request's User-Agent: com.example.dapp/v1.2.1 (Linux; Android 7.0; SM-G930V Build/NRD90M) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.125 Mobile Safari/537.36

Result: Request is allowed and all other user-agent requests are rejected

To prevent a third party from using your Project ID on their website, you can allowlist approved HTTP Origins from where the Project ID can be used.

If you are deploying your application to mydapp.example.com, adding mydapp.example.com to your HTTP Origin allowlist will ensure any traffic that does not include Origin: mydapp.example.com in the HTTP request will be rejected.

Matching Behavior

HTTP Origin matching supports wildcard subdomain patterns similarly to TLS certificates, where the left-most sub-domain may be a replaced with the special * wildcard to match any subdomain. The * matches a single sub-domain, and can only appear as the left-most portion of an entry.

The URL schema is optional, and can be either http://, https:// or any other schema you want to limit. If the schema is included in the allow list entry, then the Origin must have the same schema. Furthermore, an entry with only a schema will limit requests to Origins of that schema.

Example

Allowlist entry: https://*.example.com

Request's Origin Header: https://myapp.example.com

Result: The request above is is allowed, as both the schema and domain name match. Any requests from origins not matching https://*.example.com are rejected. This would include http://myapp.example.com (non-matching schema), https://myapp.somewhereelse.net (base domain does not match) or https://subdomain.myapp.example.com (wildcard can only match one level of sub-domains).

You can control 3 monthly quotas from your project's settings page:

• Storage quota: maximum allowed total storage (e.g: 0.001 GB)
• Data transfer UP quota: maximum allowed data/month sent to the IPFS service (e.g: 0.001 GB)
• Data transfer DOWN quota: maximum allowed data/month retrieved from the IPFS service (e.g: 0.001 GB)

If you set it to zero, you completely disable that function (for example, zero transfer up means you can’t add any data). If you clear the field and submit, there is no quota set anymore.

Infura projects will be subject to rate limits after exceeding their request count during a short time window. These rate limits are in place to ensure the reliability of our service for everyone using it. The current rate limits can change without notice in the future.

Users performing authenticated requests associated with a particular project have wider rate limits, and can achieve more requests per second.

Write API calls have 10 requests/sec limit for the following endpoints:

"/api/v0/add",
"/api/v0/block/put",
"/api/v0/dag/put",
"/api/v0/object/put",
"/api/v0/pin/add"

You can retrieve IPFS data using the API with a limit of 100 requests/sec via the remaining read-only methods such as:

"/api/v0/cat"
"/api/v0/get"
"/api/v0/dag"

Making API calls without project authentication limits you to 12 write requests/min, and content retrieval is possible at 10 requests/sec rate.

Accessing Gateway content via Subdomain https://{CID}.ipfs.infura-ipfs.io or Path resolution style https://infura-ipfs.io/ipfs/{CID} is limited to 2 requests/sec.

Your API response will have HTTP Status Code 429 and contain an error response: Too Many Requests.

Infura recommends Subdomain resolution style to access the Gateway content:

https://{CID}.ipfs.infura-ipfs.io/{optional path to resource}

Path resolution has the following URL structure:

https://infura-ipfs.io/ipfs/{CID}/{optional path to resource}

Supported for compatibility reasons but is likely to be removed in the future. Path resolution presents a security risk as all content shares the same origin from the browser's perspective, leading to a potential security breach.

All Path Gateway requests redirect to Subdomain, which means they are also slower.

Arguments are added through the special query string key arg:

curl -X POST "https://ipfs.infura.io:5001/api/v0/cat?arg=QmeGAVddnBSnKc1DLE7DLV9uuTqo5F7QbaveTjr45JUdQn"

Note that arg can be used multiple times to signify multiple arguments.

Flags commonly used with the IPFS CLI are added through the query string. For example, the --encoding=json flag is the &encoding=json query parameter below:

> curl -X POST "https://ipfs.infura.io:5001/api/v0/object/get?arg=QmaaqrHyAQm7gALkRW8DcfGX3u8q9rWKnxEMmf7m9z515w&encoding=json"
{
  "Links": [
    {
      "Name": "index.html",
      "Hash": "QmYftndCvcEiuSZRX7njywX2AGSeHY2ASa7VryCq1mKwEw",
      "Size": 1700
    },
    {
      "Name": "static",
      "Hash": "QmdtWFiasJeh2ymW3TD2cLHYxn1ryTuWoNpwieFyJriGTS",
      "Size": 2428803
    }
  ],
  "Data": "CAE="
}

::: tip Some arguments may belong only to the CLI but appear here too. These usually belong to client-side processing of input, particularly in the add command. :::

Status codes used at the RPC layer are simple:

• 200 - The request was processed or is being processed (streaming)
• 500 - RPC endpoint returned an error
• 400 - Malformed RPC, argument type error, etc
• 403 - RPC call forbidden
• 404 - RPC endpoint doesn't exist
• 405 - HTTP Method Not Allowed

Status code 500 means that the requested RPC function does exist, but IPFS was not able to fulfill the request because of an error. To know the reason, you have to look at the error message that is usually returned with the body of the response (if no error, check application logs).

Streaming endpoints fail as above, unless they have started streaming. That means they will have sent a 200 status code already. If an error happens during the stream, it will be included in a Trailer response header (some endpoints may additionally include an error in the last streamed object).

A 405error may mean that you are using the wrong HTTP method (i.e. GET instead of POST), or that you are not allowed to call that method (i.e. due to CORS restrictions when making a request from a browser).