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. Your API key must be valid for the region URL you're making a request to.

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:

• Node Service only
• Gas Station only
• Wallet Services only
• Multiple services

Aptos Node Service

Region support: US1 (Virginia) - make sure this region is selected in your dashboard.

When you create an access key in your dashboard with Node Service rights, you must provide five values in addition to selecting the service (as shown below). The "Aptos access key allotments" table on the right will show you have much QPS you have left to assign on the network. Your limits will vary based on your plan.

1. The chain (Aptos).
2. The network the key is valid for.
3. The REST API requests per second (QPS) limit for the key.
4. The GraphQL compute units per second (CUPS) for the key.
5. 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

Region support: US East - us1 - make sure this region is selected in your dashboard.

Note: When using the gas_sponsorAndSubmitSignedTransaction request, you will need to create a key with rights to Node Service also to perform the submit step - see the multiple services example, or just add node service to the image below.

When you create an access key in your dashboard 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. For guidance on creating a Gas Station fund see the Aptos Gas Station page of our Help Center.

When creating a key with Gas Station rights, you need to provide five values (as shown in the image below). The "Aptos access key allotments" table on the right will show you have much QPS you have left to assign on the network. Your limits will vary based on your plan.

1. The chain (Aptos).
2. The network the key is valid for.
3. The Gas Station fund on that network that the key is linked to.
4. The QPS for the key.
5. 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

Region support: US East - us1 - make sure this region is selected in your dashboard.

Note: When using Invisible Wallets, you will need to create a key with rights to multiple services to perform certain operations like sponsoring and executing a transaction for the wallet.

When you create an access key in your dashboard with Wallet Services rights, you need to provide two values in addition to selecting the service (as shown in the image below). The "Aptos access key allotments" table on the right will show you have much QPS you have left to assign for Wallet Services. Your limits will vary based on your plan.

1. The chain (Aptos).
2. The key's QPS.
3. 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: Multiple Services

Region support: US East - us1 - make sure this region is selected in your dashboard.

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 Aptos 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 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. For guidance on creating a Gas Station fund see the Aptos Gas Station page of our Help Center.

When you create an access key in your dashboard with a combination of Node Service, Gas Station, and Wallet Service rights, you need to provide the following values in addition to selecting the services (as shown in the image below). The "Aptos access key allotments" table on the right will show you have much QPS you have left to assign for each service (on the given network for Node and Gas Station, and for your workspace as a whole for Wallet Services).

1. The chain (Aptos).
2. The network the Gas Station and/or Node Service rights of the key are valid for (Wallet Service keys are network agnostic).
3. The REST API requests per second (QPS) limit for the key.
4. The GraphQL API compute units per second (CUPS) for the key.
5. The Gas Station fund on that network that the key is linked to if the key has Gas Station rights. For guidance on creating a Gas Station fund see the Aptos Gas Station page of our Help Center.
6. The Gas Station QPS for the key.
7. The Wallet Services QPS for the key.
8. 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

You create keys in the Access Keys page of your Shinami dashboard. Below, we show an example of creating a key with rights to:

• Node Service only
• Gas Station only
• Wallet Services only
• Multiple services

Sui Node Service

Region support:

When you create an access key in your dashboard with Node Service rights, you must provide five values in addition to selecting the service (as shown in the image below). The "Sui access key allotments" table on the right will show you have much QPS you have left to assign on the network. Your limits will vary based on your plan.

1. The chain (Sui).
2. The network the key is valid for (e.g. "Sui Mainnet")
3. The requests per second (QPS) limit for the key.
4. (deprecated) The total active WebSocket Service connections and the total active subscriptions the key is allowed. The number you set applies to both connections and subscriptions. (Note: websocket service is being retired by Mysten very soon. See the notice at the top of the WebSocket API doc. )
5. 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 Gas Station

Region support: US East - us1 - make sure this region is selected in your dashboard.

When you create an access key in your dashboard 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. For guidance on setting up a Gas Station fund, see the Sui Gas Station page of our Help Center.

When creating a key with Gas Station rights, you need to provide five values in addition to selecting the service (as shown in the image below). The "Sui access key allotments" table on the right will show you have much QPS you have left to assign on the network. Your limits will vary based on your plan.

1. The chain (Sui).
2. The network the key is valid for (e.g "Sui Testnet").
3. The QPS limit for the key.
4. The Gas Station fund on that network that the key is linked to.
5. 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

Region support: US East - us1 - make sure this region is selected in your dashboard.

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 in your dashboard with only Wallet Services rights, you must provide three values in addition to selecting the service (as shown in the image below). The "Sui access key allotments" table on the right will show you have much QPS you have left to assign for Sui Wallet Services. Your limits will vary based on your plan.

1. The chain (Sui).
2. A QPS limit for the key.
3. 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

Region support: US East - us1 - make sure this region is selected in your dashboard.

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. For guidance on setting up a Gas Station fund, see the Sui Gas Station page of our Help Center.

When you create an access key in your dashboard with rights to all services, you'll need to provide the following values in addition to selecting the services. The "Sui access key allotments" table on the right will show you have much QPS you have left to assign for each service (on the given network for Node and Gas Station, and for your workspace as a whole for Wallet Services).

1. The chain (Sui).
2. The Network the Node Services and Gas Station rights of the key are valid for (Wallet Service rights are chain agnostic).
3. The Node Service QPS and WebSocket connection + subscription limits for the key (Note: websocket service is being retired by Mysten very soon. See the notice at the top of the WebSocket API doc. )
4. The Gas Station QPS for the key.
5. The Gas Station fund the key is linked to (on the network is has rights to).
6. The Wallet Services QPS for the key.
7. 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. For domain allowlists, you can prefix the domain with *. to allow all sub-domains, e.g. *.example.com.

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.

Updating a key's rate limits

After making a key, you can update it's QPS/CUPS limits for the services it has rights to. First, click the + next to an access key in the Access Keys table to expand the row and display the key editor.

Adjust the QPS / CUPS limits up and down as you prefer, making sure you stay within the limits for your workspace. When you're done, click "Save".

Example partial success with a success and error message

Be careful: sometimes an edit to a key will be partially successful. You might successfully update one limit but not another because it would have taken the key above your total QPS/CUPS allotment for that service. In the case of a failure, you'll see an error message on the top right of the screen that describes it. If you're not sure what happened, go back to the key and check it's limits.

Checking your QPS/CUPS usage versus your total allowed

At the top of the page, select the chain your interested in and the allotment table will appear. It will show you the total possible you can assign for each service and how much is being used. If you have a disabled key, it does not count toward your usage. Highlighted in the image is that for my active Gas Station keys, I have assigned 20 out of 30 possible QPS on Testnet. Your allotments for each service will vary based on your plan.

Appendix

Node service sticky-routing

Applies to Aptos and Sui Node Services

Context: we run multiple nodes for great uptime and freshness

We run multiple nodes behind our node services to provide you with the best up-time and the freshest blockchain data possible. For example, to ensure high availability, we do rolling restarts for the regular protocol upgrades that Aptos and Sui have. On occasion a node can have also build up a backlog of transaction blocks/checkpoints that it's processing. If it falls behind by more than a few seconds, we'll block it from serving requests until it catches up so that all your reads have fresh data.

While the above means we can provide you a performant and reliable service, there are times when you as a user want to ensure that consecutive reads are made from the same node.

Issue: Time traveling reads 😵

If one node is just a few seconds behind the latest transaction block/checkpoint, we'll still let it answer requests to provide you with great uptime. Still, a few seconds can mean the difference between a user owning an NFT and not, if that time period is when the user bought or sold the NFT.

Read example: no sticky routing

A user sells an NFT at block/checkpoint X. Shinami is running two nodes: N1, N2.

The user saw the contents of their wallet jump from 3 to 4 to 3 again because the second read was from a node a block/checkpoint behind the other!

Write example: no sticky routing

Your app creates a transaction for the user to buy an NFT that is finalized at block/checkpoint X. Shinami is running two nodes: N1, N2.

We polled node N1 to ask when the transaction's effects were processed, but then we read the user's wallet contents from N2, which was a block/checkpoint behind. So, we thought the purchase would be reflected but the user still has 3 NFTs and not 4!

Solution: sticky routing

All queries to the Shinami Node Service have sticky routing enabled so that requests from the same (IP address, API key) pair go to the same node. This will solve the inconsistency issues referenced above save for a few edge scenarios:

• A protocol upgrade where we issue rolling restarts of our nodes
• A node falls behind on backlog processing and is taken out of rotation.

Read example: with sticky routing

A user sells an NFT at block/checkpoint X. Shinami is running two nodes: N1, N2.

In this case, regardless of whether node N2 is fully up to date or is processing a backlog of a couple transaction blocks/checkpoints, you and your users will experience events in the order they happened and have a consistent view of the wallet.

Write example: with sticky routing

Your app creates a transaction for the user to buy an NFT that is finalized at block/checkpoint X. Shinami is running two nodes: N1, N2.

In this case, we can be confident that once we get a response from Shinami Node Service that the node we're talking to knows about the transaction we care about, a subsequent read will reflect the results of that transaction (since it's a read from the same node).

Opting out of sticky routing

If your use case has more relaxed consistency requirements and does not require sticky routing, you have the option to disable it by using the following header on requests that don't need it: Shinami-Disable-Sticky: true. Generally, API keys you use on the FE for your end users will get distributed across nodes even with sticky routing because they'll have different IP addresses.

Reasons why you might want to use the Shinami-Disable-Sticky: true header:

1. You have an Enterprise dedicated node plan and you send requests from a very limited set of (IP, API key) pairs (e.g. you use one or two backend keys sent from one or two locations). In this case, disabling sticky routing on certain requests will mean we'll route those requests to the node with the most capacity to spare. This means you'll better distribute your requests across your nodes for improved stability and latency at high request volumes.
2. You have a Free or Pay-As-You-Go account and you want to be kind to us and your fellow Shinami users. Disabling sticky routing on requests that don't need it will route them to the node with the most capacity to spare, which helps ensure the best stability and latency for you and your fellow Shinami users.