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 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.

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

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

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.

The chain (Aptos).
The key's QPS.
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

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).

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 REST API requests per second (QPS) limit for the key.
The GraphQL API compute units per second (CUPS) for the key.
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.
The Gas Station QPS for the key.
The Wallet Services QPS for the key.
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:

Sui Node Service

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.

The chain (Sui).
The network the key is valid for (e.g. "Sui Mainnet")
The requests per second (QPS) limit for the key.
(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. )
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

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.

The chain (Sui).
The network the key is valid for (e.g "Sui Testnet").
The QPS limit for the key.
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 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.

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

The chain (Sui).
The Network the Node Services and Gas Station rights of the key are valid for (Wallet Service rights are chain agnostic).
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. )
The Gas Station QPS for the key.
The Gas Station fund the key is linked to (on the network is has rights to).
The Wallet Services QPS for the key.
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 is for a key with rights to all Aptos services, but the flow is the same for all keys.

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.