Authorization

To start integrating the SDK, you’ll need an active developer account.

License

The SDK can only be used with an active license. The license is fetched automatically whenever the SDK is initialized - internet connection is required for the first SDK usage on any device.

On mobile devices the license is locally persisted and valid for 3 days without requiring connectivity with the licensing server.

API key

In order to initialize the SDK on any platform, you’ll need an API key. The API key consists of 32 hex characters (such as aaaa00baba11abba1081081234567890) and is connected with a particular license.

You can access your API keys in the Customer Dashboard .

API key type guidance:

• A Web key must be used with the browser-based Web SDK.
• A Mobile key must be used with native SDKs and native wrappers such as Android, iOS, Flutter, React Native, Capacitor, MAUI, and Linux headless SDKs.
• Upgrading to a newer SDK package does not require API key reissuance.

The SDK is validated against a platform-specific license flow (web for the Web SDK, mobile for native and native-wrapper SDKs). A key or token from the wrong license flow may therefore surface as INVALID_API_KEY.

Short-lived tokens

In production integrations, especially on Web or in distributed client apps, you may prefer not to embed a permanent API key directly in the client.

For that case, your backend can issue a short-lived token and pass it to the SDK during initialization. The SDK uses that token in place of the API key for the current initialization flow.

Short-lived tokens are still tied to the underlying license and platform flow. For example, a token generated for a Web license must be used with the Web SDK, and a token generated for a mobile license must be used with native or wrapper SDKs.

A token from the wrong license flow may surface as INVALID_API_KEY.

See Short-lived tokens for setup details.

License vs API key vs token

These terms are related but not interchangeable:

• License: the commercial entitlement and usage limits.
• API key: the permanent credential used to initialize the SDK against a specific license.
• Short-lived token: a temporary credential generated by your backend and passed to the SDK instead of a permanent API key.

Troubleshooting INVALID_API_KEY and license initialization

If SDK initialization returns INVALID_API_KEY or another license-validation failure, verify the following first:

• The API key type matches the SDK platform being initialized.
• The associated license or trial remains active.

When short-lived tokens are used, the SDK client still requires the correct platform-compatible license behind that token.

Usage attribution

Depending on your contract, SDK usage will be counted in one of three modes:

• Per-use
• Per-user (automatic)
• Per-user (manual)

Please see shen.ai/pricing  for the base available pricing plans.

Per-use

In this default mode, usage is counted when a new measurement starts and runs at least until Heart Rate is first displayed (about 7 seconds). If a measurement is stopped and restarted within the same SDK session, the resumed run continues the existing usage. A new measurement is only counted after the previous one has finished successfully.

Per-user (automatic)

In this mode, the SDK automatically generates a unique identifier at the first initialization on a given device/browser. This identifier is then persisted locally and any further SDK sessions are attributed to the same user.

The final usage will be counted based on the amount of unique monthly active users.

Per-user (manual)

In case of a per-user (manual) contract you’ll need to explicitly pass a user identifier to properly attribute license usages. This way, if you already have a way of identifying your users, you can attribute SDK usage across different platforms and devices to a single user.

Please see the detailed instructions in per-platform guides to see how to pass the API key and User ID during SDK initialization.