API Keys

Introduction

Immutable authenticates and authorises your Immutable zkEVM API requests using your environments' API keys.

Types of keys and when to use them

💡Note

In the Immutable Hub, you can create multiple projects, and in each project you can create multiple environments. There is a limit of 1 Secret API Key and 1 Publishable Key per environment.

Immutable offers three types of keys:

1. Publishable Key,
2. Secret API Key and
3. Rate Limit Key

Type	Value	When to use
Publishable key	A string that starts with pk_imapik-	Publishable Keys are used to identify your integration for tracking and analytics purposes. It's not a secret key and is safe for client-side applications, like web browsers, mobile applications and game clients as it is designed to be publicly safe and anonymous.
Secret API key	A string that starts with sk_imapik-	Secret API Keys are used to authenticate and authorise your backend integrations with Immutable. Don’t expose this key on a website or embed it in a game client or mobile application.
Signable key	Ethereum address	Signable keys are secure cryptographic keys that enables Immutable to sign transactions on your behalf.
Rate Limit Key	A string	Rate limit keys are used to increase the default rate RPC rate limit. This is only available for managed partners.

To differentiate between testnet and mainnet keys, testnet keys start with pk_imapik_test- and sk_imapik_test- respectively.

💡Caution

Keep your secret API key safe

Anyone can use your secret API key to perform "write" API calls, such as refreshing your asset metadata. You can keep your key safe by following these best practices:

• Access to the secret API key should only be given to those who need it.
• Don’t store your secret API key in a version control system.
• Your secret API key should be stored in a password manager or secrets management service. And used via environment variables or the like.
• Don’t use your secret API key where it could be exposed to an attacker, such as in a game client, mobile or web application.

Creating and Managing API keys

You can create and manage your keys in the Immutable Hub. The Immutable Hub serves as a portal for creating, displaying, and refreshing API keys.

To create your keys, navigate to the "Keys" menu item within your project and environment to manage your API keys.

Please note that your Secret API key is only revealed during creation. Ensure that you save this key securely as it will not be displayed again.

How to use API Keys

Using the Publishable Key

Publishable Keys are used to identify your integration for tracking and analytics purposes. It's not a secret key and is safe for client-side applications, like web browsers, mobile applications and game clients as it is designed to be publicly safe and anonymous.

const baseConfig = {
  environment: config.Environment.PRODUCTION,
  publishableKey: YOUR_PUBLISHABLE_KEY, // Replace with your Publishable Key from the Immutable Hub
};

curl --request GET \
  --url https://api.sandbox.immutable.com/v1/chains/imtbl-zkevm-testnet/collections \
  -H 'Content-Type: application/json' \
  -H 'x-immutable-publishable-key: [YOUR_PUBLISHABLE_KEY]'

Using the Secret API Key

Secret API Keys are used to authenticate and authorise your backend integrations with Immutable (eg. deploying a contract). Don’t expose this key on a website or embed it in a game client or mobile application.

View on GitHub

import { config, blockchainData } from '@imtbl/sdk';

const API_KEY = 'YOUR_API_KEY';
const PUBLISHABLE_KEY = 'YOUR_PUBLISHABLE_KEY';

const client = new blockchainData.BlockchainData({
  baseConfig: {
    environment: config.Environment.PRODUCTION,
    apiKey: API_KEY,
    publishableKey: PUBLISHABLE_KEY,
  },
});

curl --request POST \
  --url https://api.sandbox.immutable.com/v1/chains/imtbl-zkevm-testnet/collections/0x8a90cab2b38dba80c64b7734e58ee1db38b8992e/refresh-metadata \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-immutable-api-key: [YOUR_SECRET_API_KEY]' \
  --data '{
  "collection_metadata": {
    "name": "Gigantic Lizards",
    "symbol": "GLZ",
    "description": "This is the Gigantic Lizards collection",
    "image": "https://some-url",
    "external_link": "https://some-url",
    "contract_uri": "https://some-url",
    "base_uri": "https://some-url"
  }
}'

Read more about the Immutable the TypeScript SDK.

List of endpoints that require Secret API Key authorization

Name	Endpoint	Method	Type
Refresh metadata	/v1/chains/{chain_name}/collections/{contract_address}/refresh-metadata	POST	Metadata Refresh
Refresh Stacked metadata	/v1/chains/{chain_name}/collections/{contract_address}/metadata/refresh-metadata	POST	Metadata Refresh
Refresh NFT metadata	/v1/chains/{chain_name}/collections/{contract_address}/nfts/refresh-metadata	POST	Metadata Refresh
Mint NFTs	/v1/chains/{chain_name}/collections/{contract_address}/nfts/mint-requests	POST	NFTs
List mint requests	/v1/chains/{chain_name}/collections/{contract_address}/nfts/mint-requests	GET	NFTs
Get mint request	/v1/chains/{chain_name}/collections/{contract_address}/nfts/mint-requests/{reference_id}	GET	NFTs

Using the signable key

Signable keys are secure cryptographic keys that enable Immutable to sign transactions on your behalf without exposing your private keys.

Once you've created a signable key in Hub, the ethereum public address derived from the key will be shown.

This address can then be granted the SIGNER_ROLE for your contracts as needed. This is relevant to products that require Immutable to sign transactions on your behalf, such Assets Crafting and the Primary Sales widget.

Refer to the grant signer role to the Immutable API documentation for more information.

How to refresh Secret API Keys

You can refresh your Secret API keys in the Immutable Hub. Once you create a Secret API key, you will get options to reveal, copy or refresh right next to it. Note that when you refresh a Secret API Key, the existing key will stop working.

Rate Limits

RPC calls to the default zkEVM RPC are rate limited. You can use your API key to increase this rate limit.

const baseConfig = {
  environment: config.Environment.PRODUCTION,
  rateLimitingKey: YOUR_RATE_LIMITING_KEY,
};

curl --request GET \
  --url https://api.sandbox.immutable.com/v1/chains/imtbl-zkevm-testnet/collections \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: [YOUR_RATE_LIMITING_KEY]'

Default Rate Limit

If a request to the RPC endpoint does not include an x-api-key header, it is subject to the default rate limit.

The default rate limit is set to 1500 calls per 5 minutes, which equates to an average of 5 calls per second.

Rate Limit with x-api-key

If an x-api-key header is included in the RPC request (as a partner), the rate limit is determined by the associated partner usage plan. These limits are typically higher.

Use the x-api-key together with x-immutable-api-key where appropriate.

Invalid x-api-key

If the provided x-api-key in the request header is invalid (e.g., non-existent or malformed), the request will be rejected with a 403 Forbidden response.