Securing Your Credentials

Authenticating using a Project ID

Infura's Ethereum APIs require a valid Project ID to be included with your request traffic. This identifier should be appended to the request URL.

curl https://<network>.infura.io/v3/YOUR-PROJECT-ID

Authenticating using a Project ID and Project Secret

As additional protection for your request traffic, you should use HTTP Basic Authentication to access our API when you are able to ensure the confidentiality of the Project Secret:

curl --user :YOUR-PROJECT-SECRET \
  https://<network>.infura.io/v3/YOUR-PROJECT-ID

Note that the user field of the request is left blank and the project id is passed in the URL.

Require a Project Secret

By default, the Project Secret is optional. If you know you will only be interacting with Infura APIs from a secure environment (e.g. your backend web application), you can toggle the Private Secret Required setting in your Project's configuration page under the Security section.

Choose a Network

Use one of these endpoints as your Ethereum client provider or IPFS endpoint.

NOTE: Be sure to replace YOUR-PROJECT-ID with a Project ID from your Infura Dashboard.

NetworkDescriptionURL
MainnetJSON-RPC over HTTPshttps://mainnet.infura.io/v3/YOUR-PROJECT-ID
MainnetJSON-RPC over websocketswss://mainnet.infura.io/ws/v3/YOUR-PROJECT-ID
RopstenJSON-RPC over HTTPShttps://ropsten.infura.io/v3/YOUR-PROJECT-ID
RopstenJSON-RPC over websocketswss://ropsten.infura.io/ws/v3/YOUR-PROJECT-ID
RinkebyJSON-RPC over HTTPShttps://rinkeby.infura.io/v3/YOUR-PROJECT-ID
RinkebyJSON-RPC over websocketswss://rinkeby.infura.io/ws/v3/YOUR-PROJECT-ID
KovanJSON-RPC over HTTPShttps://kovan.infura.io/v3/YOUR-PROJECT-ID
KovanJSON-RPC over websocketswss://kovan.infura.io/ws/v3/YOUR-PROJECT-ID
GörliJSON-RPC over HTTPShttps://goerli.infura.io/v3/YOUR-PROJECT-ID
GörliJSON-RPC over websocketswss://goerli.infura.io/ws/v3/YOUR-PROJECT-ID
IPFSIPFS Gatewayhttps://ipfs.infura.io/ipfs/
IPFSIPFS APIhttps://ipfs.infura.io:5001/api/

Make Requests

JSON-RPC Methods

Below is a quick command line example using curl:

# Be sure to replace YOUR-PROJECT-ID with a Project ID from your Infura dashboard
$ curl -X POST \
-H "Content-Type: application/json" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []}' \
"https://mainnet.infura.io/v3/YOUR-PROJECT-ID"

The result should look something like this:

$ {"jsonrpc": "2.0","result": "0x657abc", "id":1}

NOTE: "0x657abc" will be replaced with the block number of the most recent block on that network

Read more about JSON-RPC

It's important to note that JSON-RPC requests are transport agnostic, the same requests can be made over HTTPS, Websockets, or other message passing environments. For example, the same request could be made with websockets:

# Be sure to replace YOUR-PROJECT-ID with a Project ID from your Infura dashboard
$ wscat -c wss://mainnet.infura.io/ws/v3/YOUR-PROJECT-ID
> {"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []}
< {"jsonrpc":"2.0","id":1,"result":"0x657abc"}

Subscriptions and Filters

Note that the newer, experimental Ethereum "pub/sub" subscription support is only supported over "stateful" transports such as Websockets. Subscription and filter requests cannot be made over HTTPS.

Read more about RPC PUB SUB

Securing With Allowlists

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.

Understanding Allowlist Behavior

  • 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.

User-Agents

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

HTTP Origin

To prevent a third party from using your Project ID on their website, you can allowlist approved HTTP Origins from where it 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.

Example

Allowlist entry: *.example.com

Request's Origin Header: myapp.example.com

Result: Request is allowed. Any requests from origins not matching *.example.com are rejected

Ethereum Addresses

If you know your application will only be querying data from specific smart contracts or address sources, add those addresses to your Ethereum Address Allowlist.

When an address is added to the allowlist, any API requests which query addresses not in the allowlist are rejected.

Allowlist Compatible Request Methods

The following RPC methods take an Ethereum address parameter and thus are compatible with allowlisting.

  • call
  • estimateGas
  • getLogs
  • getBalance
  • getCode
  • getStorageAt
  • getTransactionCount

Example

Allowlist entry: 0xfe05a3e72235c9f92fd9f2282f41a8154d6d342b

Request:

curl -H 'Content-Type: application/json' \
      -X POST \
      -d '{"id":1, "jsonrpc": "2.0", "method": "eth_getBalance","params":["0xfe05a3e72235c9f92fd9f2282f41a8154d6d342b", "latest"]}' \
      https://mainnet.infura.io/v3/YOUR-PROJECT-ID

Result: Request is allowed. Any compatible request methods which include only non-allowlisted addresses as a parameter will be rejected.

Best Practices

Protecting a client-side credential can be simple or complex depending on the scenario. Use the allowlist features that best fit your application. The list of items below are recommendations we'd like to make to help you make informed decisions for your application.

  • Whenever you are making API requests and can ensure the PROJECT_SECRET will not be exposed publicly, include it in your requests.
  • Don't just use the User-Agent or Origin allowlist, use both whenever possible.
  • Don't reuse Project IDs across projects.
  • Create a new Project ID for each application. This allows you to allowlist the contract addresses relevant to that application.
  • Never expose your PROJECT_SECRET in client-side code such as Javascript imported into a webpage or iOS or Android apps. Use the other options for securing public project IDs instead.

Other Resources