Integrate applications with Kadena SpireKey

To work with Kadena SpireKey, an application must be able to connect to the Kadena SpireKey URL and pass some information back and forth. Kadena SpireKey handles the account registration and authentication based on the information your application provides when it connects to the SpireKey URL.

You can view the interaction between an application and Kadena SpireKey as a simple two-way conversation. You initiate the conversation from your application by connecting to the Kadena SpireKey URL to request account information. Kadena SpireKey determines if the account exists or needs to be registered and either creates or accesses the account information. Kadena SpireKey returns information about the account to your application.

Your application parses the information to provide services to the user and to prepare a transaction and bundle it into signing request. Your application then connects to the Kadena SpireKey URL to request the account signatures required to complete the transaction. If the user approves and successfully signs the transaction, Kadena SpireKey returns the signature to your application. If only one signer is required, the transaction is ready for processing on the blockchain. If a transaction requires multiple signatures from different accounts, the application is responsible for collecting the signatures required to construct the transaction before submitting the transaction for processing on the blockchain.

In summary, the application is responsible for:

You can connect to Kadena SpireKey and request account information from an application by send a GET request to the Kadena SpireKey /connect endpoint and specifying a return URL with appropriate parameters to return the user to your application.

The following example illustrates an application running locally on http://localhost:3000 that's deployed on the testnet04 network:

https://spirekey.kadena.io/connect?returnUrl=http:/localhost:3000&networkId=testnet04

As you see in this example, the returnUrl is a URL-encoded query parameter that Kadena SpireKey uses to redirect users after they connect. When users are redirected to the /connect endpoint, Kadena SpireKey checks whether they have an account. Users who don't have an account are automatically redirected to the /register endpoint to register a passkey. After registering a passkey for the account, users can select the new account and return to your application.

In many cases, applications are only deployed on a specific network and chain. For example, your application might only run on the Kadena test network and only allow transactions on chain 7 of the test network. You must specify the networkId parameter in the returnUrl. The chainId parameter is optional. However, if users attempt to connect using an account that exists on a different chain than the chain your application runs on, they won't be able to sign and complete transactions in your application.

To prevent this type of transaction failure, you can specify the chainId as a query parameter when connecting to the Kadena SpireKey URL. The chainId parameter limits the accounts that users can select from to accounts created on the specified chain.

In the following example URL, the networkId is testnet04 and the chainId parameter is set to 7:

https://spirekey.kadena.io/connect?returnUrl=http://localhost:3000&networkId=testnet04&chainId=7

You can change the value to any of the twenty available chains on the Kadena network, as needed. Note that the chains are zero-indexed, so the first chain is 0 and the last one is 19.

In addition to the application URL, the network identifier, and the chain identifier, you can customize the reason that your application asks users to connect to their Kadena SpireKey account.

To display more detailed information about why your application requires account information from the user, add the reason query parameter to the Kadena SpireKey URL. You must use URL encoding to specify the value for this parameter. For example:

https://spirekey.kadena.io/connect?returnUrl=http://localhost:3000&networkId=development&reason=Before%20you%20complete%20this%20purchase,%20select%20an%20account.

Depending on the network and other factors that affect network activity—such as the number of requests and available nodes—confirming that an account has been created on the blockchain can take some time. Because most applications don't need accounts to be created onchain before preparing transaction, Kadena SpireKey supports optimistic onboarding by default.

With optimistic onboarding, users are immediately redirected back to your application without waiting for the account creation transaction to be confirmed on the blockchain. In most cases, creating user accounts in a background process is safe. However, you must ensure that your application only submits signed transactions after all signer accounts exist on the blockchain.

If you want to prevent optimistic onboarding, you can set the optimistic parameter to false when connecting to the Kadena SpireKey URL.

After creating or selecting a Kadena SpireKey account, users are redirected to your application with their public account details appended as a base64-encoded user object. You can parse the decoded parameter value as a JSON object. The resulting user object consists of key and value pairs similar to the following set of properties:

{ "accountName": "c:68foI6nNAYN_a6Nu_CNEGiKyVDJlGxKC0dOZLBq6ZeW", "alias": "Alice", "credentials": [ { "id": "d2eYT3zAklMgZZJNjQ3zJxZ6kuT4tkd_ndePIEWK3Nd", "publicKey": "WEBAUTHN-a50102032620012158209a4e83b6d734880b926c0e74bce8e449ac03f0998cb224999d5039651c24534d225820f2804f3c424918786a978c56956628dc93d0d32182973db187084579503cea3c", "type": "WebAuthn" } ], "pendingTxIds": ["gzlhITOU8hMaOXHKcSJgxLl0Ir8j2crUnFh20cGcxsR"] }

As illustrated in the previous example, after decoding and parsing the account details, you should see the following properties:

If you use the optimistic flow for onboarding users, you can use the chainweb-data API to poll the status of pending transaction using the identifier from the pendingTxIds property. For example, if the pendingTxIds property in the user object is gzlhITOU8hMaOXHKcSJgxLl0Ir8j2crUnFh20cGcxsR, the chainweb-data API request would look like this:

https://estats.testnet.chainweb.com/txs/tx?requestkey=gzlhITOU8hMaOXHKcSJgxLl0Ir8j2crUnFh20cGcxsR

You should note that there are scenarios where the pendingTxIds property might contain transaction identifiers that aren't related to account creation, but these are beyond the scope of this guide.

If you add the /connect endpoint for Kadena SpireKey to your application, Kadena SpireKey handles the workflow for adding credentials and connecting to Kadena SpireKey accounts for your users. The following diagram illustrates the basic workflow for registering an account using Kadena SpireKey.