Skip to main content

Allowlists

Allowlists protect your project from undesirable activity.

Allowlist types restrict access to specific addresses, HTTP headers User-Agent and Origin, and API request methods.

Add the restriction details in the ALLOWLISTS section of your API key's security settings.

Allowlists in Infura project security settings

Allowlist behavior​

  • If an API key has no allowlists, all requests are accepted.
  • As soon as an API key has an allowlist definition, all requests must pass it.
  • Each API key has a maximum of 30 allowlist entries per type.
  • Each allowlist type is "AND"ed together.
  • Multiple entries of the same type are "OR"ed.

Contract addresses​

If your application only queries data from specific Ethereum smart contracts or addresses, add those addresses to the CONTRACT ADDRESSES allowlist.

Any requests which query addresses that are not in the allowlist are rejected.

The following RPC methods take an Ethereum address parameter and are compatible with this type of allowlisting.

  • eth_call
  • eth_estimateGas
  • eth_getLogs
  • eth_getBalance
  • eth_getCode
  • eth_getStorageAt
  • eth_getTransactionCount

Example request​

To allow a specific Ethereum address, click ADD and input it into the CONTRACT ADDRESSES allowlist.

Add an address to the allowlist

Test with a method from the list.

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

Result:

{"jsonrpc":"2.0","id":1,"result":"0x0"}

User agents​

To limit access to your application to specific user agents, add them to the USER AGENTS allowlist.

info

Find out more about the HTTP Header User-Agent.

When you add a User-Agent to an allowlist, any API requests originating from other platforms are rejected.

info

The USER AGENTS 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 request​

For example, to allow requests from Android phones alone, click ADD and input Android into the USER AGENTS allowlist.

Android added to USER AGENTS allowlist

Test with a simple call from a desktop terminal.

curl https://mainnet.infura.io/v3/<PROJECT_ID> \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1}'

Result:

{"jsonrpc":"2.0","error":{"code":-32002,"message":"rejected due to project ID settings"}}ash

Origins​

To limit access to your application to specific URLs, add them to the ORIGINS allowlist.

info

Find out more about the HTTP Header Origin.

When you add an origin to an allowlist, any API requests originating from other origins are rejected.

Origin allowlists support wildcard subdomain patterns.

For example, allowlist entry https://*.example.com matches https://your-app.example.com , https://our-app.example.com, and https://their-app.example.com, etc.

The origin scheme (HTTPS in the example above) is optional. However, if you include it, it must match.

info

An entry with only a scheme allows requests coming from that scheme alone.

Example request​

To limit requests to your hosted web3 application, click ADD and input mydapp.example.com into the ORIGINS allowlist.

Any requests that do not include Origin: mydapp.example.com are rejected.

API request method​

To limit the methods allowed, add them to the API REQUEST METHOD allowlist.

If the list is not empty, any method calls not specified in the list are rejected.

Use the dropdown list to select a method.

Select API REQUEST METHOD from the dropdown list

Best practices​

  • Ensure the API-KEY-SECRET is not exposed publicly, and include it in your requests.
  • Use both the User-Agent and Origin allowlists wherever possible.
  • Create a new API key for each application. This allows you to allowlist the contract addresses relevant to that application.
  • Never expose your API key in client-side code, such as Javascript imported into a webpage or iOS or Android apps. Use the other options for securing public API keys instead.
  • Avoid committing your project keys to a repo by using a package like dotenv.
info

Read our blog about using dotenv.

Last updated on