Authentication and API Keys
Learn how to authenticate and to create and manage your API access keys
Overview
How to authenticate
You can authenticate with all Shinami services via an access key passed in a header ('X-Api-Key: ACCESS_KEY'
). Some service API docs will list additional methods, but this method works across the board. We have a lot of helpful content below, but if you don't find an answer to your question you can reach out to us.
Security callout: when to send from your backend
Gas Station and Wallet Services - always send from your backend
You will need to send requests to our Gas Station and Wallet Services APIs from your backend. These services do not support CORS, so if you attempt to make requests to them from the FE you'll get a CORS error. We do this because exposing these keys on the FE is a security risk. With a Gas Station key access key, an attacker could drain your Gas Station fund associated with the key by using it to sponsor transactions. With a wallet services access key, a bad actor could sign transactions from your user's wallets.
Node Service - send from your backend when possible
You may send Node Service requests from either your frontend or backend, but we recommend backend when possible. If you expose a key with Node Service rights, a bad actor could make requests that count against your daily request allotment and your key's QPS. If exposure on frontend is necessary, you can enable a domain allowlist as a security measure. You should also create separate keys for your frontend and backend. Doing so enables you to assign each one a different maximum QPS from your total QPS allotment so that one key's requests don't lead to rate limits for the other. It also allows you to rotate them separately (see next section).
Rotating API access keys
You can disable an API access key and create a new one as needed (see Disable, enable, or delete a key).
API Access Key Limit
You can make a total of 10 API access keys. You may use this allotment across whatever combination of Shinami services and (Chain, Network) pairs that works best for you.
Create an Access Key
Aptos
You create keys in the Access Keys page of your Shinami dashboard. Below, we show an example of creating a key with rights to:
Aptos Node Service
When you create an access key with Node Service rights, you must provide five values in addition to selecting the service:
- The chain (Aptos).
- The network the key is valid for.
- The requests per second (QPS) limit for the key This applies to our Aptos REST API.
- The compute units per second (CUPS) for the key. This applies to our Aptos GraphQL API.
- A name for the key
Once you've made your selections, click "+ Create key" and the key will show up in the Access keys table below.
Aptos Gas Station
When you create an access key with Gas Station rights, you link it to a previously-created Gas Station fund on the same network. All requests for sponsorship using the key draw APT from that fund. Gas Station keys have a rate limit of 10 requests per second.
When creating a key with Gas Station rights, you need to provide four values (as shown in the image below):
- The chain (Aptos).
- The network the key is valid for.
- The Gas Station fund on that network that the key is linked to.
- A name for the key.
Once you've made your selections, click "+ Create key" and the key will show up in the Access keys table below.
Aptos Wallet Services
When you create an access key with Wallet Services rights, you need to provide two values in addition to selecting the service (as shown in the image below):
- The chain (Aptos).
- A name for the key.
Aptos: Multiple Services
When you create an access key with a combination of Node Service, Gas Station, and Wallet Service rights, you need to provide six values in addition to selecting the services (as shown in the image below):
- The chain (Aptos).
- The network the Gas Station and/or Node Service rights of the key are valid for (Wallet Service keys are network agnostic).
- The requests per second (QPS) limit for the key This applies to our Aptos REST API.
- The compute units per second (CUPS) for the key. This applies to our Aptos GraphQL API.
- The Gas Station fund on that network that the key is linked to if the key has Gas Station rights.
- A name for the key.
Sui
You create keys in the Access Keys page of your Shinami dashboard. Below, we show an example of creating a key with rights to:
Sui Node Service
When you create an access key with Node Service rights, you must provide five values in addition to selecting the service (as shown in the image below):
- The chain (Sui).
- The network the key is valid for.
- The requests per second (QPS) limit for the key.
- The total active WebSocket Service connections and the total active subscriptions (to Move events or Sui transactions) the key is allowed. The number you set applies to both connections and subscriptions. (Note: websocket service is being retired by Mysten around September-October, 2024. See the notice at the top of the WebSocket API doc. )
- A name for the key.
Once you've made your selections, click "+ Create key" and the key will show up in the Access keys table below.
Node access key QPS and WebSocket connection + subscription allotments
The "Node access key allotments" table on the same page shows you how much you can allot per network. Your billing plan determines the total QPS and WebSocket connections+subscriptions you have to use. In the image below, we've allotted 1 WebSocket subscription (which also means 1 connection) out of 40 possible subscriptions and connections on Mainnet.
You can change a key's values after creating it (see Update A Node Service key's limits). In the example above, I am on a free plan so my Node Service API calls have a per-day limit. Paid plans do not have a per-day request limit but are still subject to QPS rate limits on each access key.
Sui Gas Station
When you create an access key with Gas Station rights, you link it to a Gas Station fund you've already created on the same network. All requests for sponsorship using the key draw SUI from that fund. See our FAQ for guidance on how to set up a fund. Gas Station keys have a rate limit of 10 requests per second.
When creating a key with Gas Station rights, you need to provide four values in addition to selecting the service (as shown in the image below):
- The chain (Sui).
- The network the key is valid for (Testnet or Mainnet).
- The Gas Station fund on that network that the key is linked to.
- A name for the key.
Once you've made your selections, click "+ Create key" and the key will show up in the Access keys table below.
Sui Wallet Services
Note: When using Invisible Wallets, you will often want to create a key with rights to multiple services to facilitate transaction sponsorship, signing, and execution in one request.
When you create an access key with only Wallet Services rights, you must provide two values in addition to selecting the service (as shown in the image below):
- The chain (Sui).
- A name for the key.
You do not need to select a network because Sui wallet addresses are network agnostic (they are the same on Devnet, Testnet, and Mainnet). So, you do not need separate keys for separate networks.
Once you've made your selections, click "+ Create key" and the key will show up in the Access keys table below.
Sui: Multiple Services
Sometimes you'll need a key with rights to multiple services. An example is when using Invisible Wallets - all Invisible Wallet API methods that write to the Sui blockchain require rights to Wallet Services (for signing the transaction), Gas Station (for sponsoring the transaction), and Node Service (for submitting the transaction to the blockchain).
When you create an access key with Gas Station rights, you need to link it to a Gas Station fund you've already created on the same network. All requests for sponsorship using the key draw SUI from that fund. See our FAQ for guidance on how to set up a fund.
When setting up an API access key with rights to all services, you'll need to provide the following values in addition to selecting the services:
- The chain (Sui).
- The Network the Node Services and Gas Station rights of the key are valid for (Wallet Service rights are chain agnostic).
- QPS and WebSocket connection + subscription limits for the key (for more info, see the section on Node Service only keys). (Note: websocket service is being retired by Mysten around September-October, 2024. See the notice at the top of the WebSocket API doc. )
- The Gas Station fund the key is linked to (on the network is has rights to).
- A name for the key.
Once you've made your selections, click "+ Create key" and the key will show up in the Access keys table below.
Key management
Sender domain and IP address allowlists
If desired, you can enter a list of domains and/or IP addresses that are the only ones only allowed to make requests using a given access key. IP whitelists should only be considered when requests from a given key will only come from a fixed set of static IP addresses . If the IP address of requests with the key can vary, such as when the frontend of your application makes requests on behalf of all of your users around the world, consider a domain whitelist.
When your allowlists are empty, we accept all requests that use that key (assuming the requests are properly formatted, etc). If you've entered values into an allowlist, we check against it when getting a request from that access key. If the domain or IP address the request originates from is not in the allowlist, we'll block it with a HTTP 401 Unauthorized
. You can add up to 10 entries in both domain and IP allowlists.
Click the +
next to an access key in the Access Keys table to expand the row and display the key editor.
Then, add or remove values to either list. When done making changes, click "Save" (on small screens you may have to scroll to see the button). Note: it may take up to five minutes for the changes to take effect.
Disable, enable, or delete a key
You can disable, enable, or delete API access keys by first selecting the checkbox to the left of one or more keys in the Access Keys table and then choosing one of the options above the table. Note: it may take up to five minutes for changes to take effect.
We encourage you to opt for "disable", since deletion is unrecoverable. You may, for example, wish to keep a disabled key in your Access keys table for a while after disabling it so that you can find the key's value if needed for an investigation. If you do choose to delete a key, you'll need to then confirm the deletion through a dialog box:
Change a key's name
To change an access key's name, click the edit icon next to the name in the Access Keys table.
Then, edit the name.
When you're done, hit return or click outside of the box. The updated name will be shown.
Update a Node Service key's QPS (and, for Sui, WS connection limits)
Click the +
next to an access key in the Access Keys table to expand the row and display the key editor.
If the key has Node Service rights, you can adjust the QPS and/or WebSocket Service subscriptions (which also applies to WebSocket Service connections) the key is allotted. (Note: websocket service is being retired by Mysten around September-October, 2024. See the notice at the top of the WebSocket API doc. )
Once you're finished, click "Save" (on small screens you may have to scroll to see the button). If you're already using your full allotment for the network , you can reduce the values for a different key, save the change, and then increase them for the key you want to have higher limits. Note: it may take up to five minutes for the changes to take effect.
Updated 10 days ago