Authentication

You authenticate via an access key passed in a header ('X-Api-Key: ACCESS_KEY') or in the request url, e.g. https://api.shinami.com/node/v1/ACCESS_KEY. We recommend using a request header and not putting access keys in your request URLs for reduced visibility (in logs, etc).

A single key can have rights to one or more services. Node Service and Gas Station keys are also tied to a network (e.g. Mainnet). Wallet Service keys work on all networks because when you create a KeyPair for a wallet address on the Sui blockchain you are able to sign transactions for the same address on all networks.

Security callout: send requests from your backend

Gas Station and Wallet Services - always send from your backend

We strongly recommend having your backend server make Gas Station and Wallet Services requests in order to protect these access keys. If you expose a key with Gas Station rights, a bad actor could sponsor transactions from your fund and drain it. If you expose a wallet services 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 (if on a free plan), your bill (if on a paid plan), and your key's QPS and WebSocket connection+subscription limits (on any plan). 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 access keys. You may use this allotment across any combination of Shinami services and Sui networks that you want.

Create an API access key

You create keys in the Access Keys page of your Shinami dashboard. Below, we show an example of key creation for each service, as well as a key that works with multiple services. We also note any access key details that are service specific.

Node Service only (JSON-RPC + WebSockets)

When you create a key with Node Service rights, you must provide four values (as shown in the image below):

A name for the key.
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.

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.

Gas Station only

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 three values:

A name for the key.
The network the key is valid for (Testnet or Mainnet).
The Gas Station fund on that network that the key is linked to.

Wallet Services only (Invisible and zkLogin wallets)

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 a key with only Wallet Services rights, you must provide one value (as shown in the image below):

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.

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:

A name for the key.
The Sui network that the key has Node Service and Gas Station rights to (Wallet Services keys work on all networks).
QPS and WebSocket connection + subscription limits for the key (for more info, see the section on Node Service only keys).
The Gas Station fund the key is linked to (on the network is has rights to).

Update a Node Service key's 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.

Once you're finished, click "Save". 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.

Set sender domain and/or IP address allowlists for a key

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