Skip to main content

API Keys

Introduction

Immutable authenticates and authorises your Immutable X 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

Immutable offers two types of keys:

TypeValueWhen to use
API KeyA 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.
Rate Limit KeyA stringRate limit keys are used to increase the default rate RPC rate limit. This is only available for managed partners.
💡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.

List of endpoints that require Secret API Key authorization

NameEndpointMethod
Create collection/v1/collectionsPOST

Managing API keys

Creating API key

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. Navigate to the "API Keys" menu item within your chosen project and environment to manage your API keys.

Hub API keys page

Refreshing API key

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 limit 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 300 calls per minute, 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.

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.