Obtaining Keys

Keys are managed from the neccessory console. A key is always the same thing — a public key id and a secret — used everywhere: the Web SDK, the iOS SDK, the REST API, and the cloud tier.

What a key does carry is a mode, and the mode decides which tier it unlocks.

Cloud and on-device

Both modes sign requests identically. A key computes the metric sets enabled at its creation (billing follows the same sets); the only thing gated by application is the download of the model weights themselves, because that is what puts our models on a machine we do not control.

There is a third mode, test, which needs no application: it answers with synthetic results, is never billed, and exists so your CI has something to sign against. See test keys.

Create a cloud key

1. Go to Console → Keys.
2. Click New key. The dialog asks where the key computes — Cloud is selected by default; Test is always offered, and On-device appears once your organization's application is approved.
3. Optionally give it a name (a label for your own reference) and an expiry (365 days by default, up to never), and untick any metric sets the key should not be able to request. Leave them all ticked and the key may ask for everything.
4. The response shows the secret exactly once. Copy it and store it securely.

That is the entire setup — a cloud key can mint a cloud session and measure straight away.

The key id and the secret both start with nk_live_, or with nk_test_ on a test key. The prefix only labels the mode for a human reading a log; keys issued before the prefixes existed carry none and keep working exactly as before.

The key object

{
  "keyId": "nk_live_sRwG9z2hK2hdV4Il83J7Cw", // public — safe to embed/log, sent as x-key-id
  "secret": "nk_live_…",                     // shown ONCE at creation — copy it now, rotation is the only way back
  "name": "Production web",                  // optional label
  "mode": "cloud",                           // "cloud" | "on_device" | "test", fixed at creation
  "status": "active",                        // "active" | "disabled"
  "features": ["hrv", "bp"],                 // metric sets the key may request; null = no restriction
  "createdAt": 1767225600000,                // epoch milliseconds
  "expiresAt": 1798761600000                 // epoch milliseconds; null when the key never expires
}

Apply for on-device access

On-device means the model weights run on the end user's phone or browser. That is the one thing we do not hand out on sign-up, so it goes through a short review.

1. In the console, open On-device and submit a request there. Only one can be open at a time.
2. The form is short — five things:
   • the platforms you need, one or more of ios, web, android (entitlements are issued per platform);
   • the use case — where the measurement will run, what you are building and for whom;
   • your company name;
   • your expected monthly volume (optional — a whole number of measurements);
   • two consents: that an on-device result is not attested by our server and is not a basis for a medical conclusion, and that you will not extract, unpack or redistribute the models.
3. We review and return one of four outcomes: approved, rejected, more information needed, or later revoked.

The use case is the only field a human reads, so write it as if to an engineer, not to a sales form. "Occupational health screening in factories in the EU, offline shifts, no network on the plant floor" gets a faster decision than "we need vitals".

A request waiting on more information needed still counts as the one open request: you answer it by replying to the address the console shows you (support@neccessory.com), not by filing a new one.

What approval gives you

• Your organization's on-device status flips to approved, recorded with the decision date.
• On-device appears in the mode picker on Console → Keys, so new keys can be created in on_device mode. A key's mode is fixed at creation — an existing cloud key is not converted, you issue a new one.
• Those keys may call POST /sdk/v1/models/grant, which is what lets a client download the model weights — per platform and per release channel. Without approval that call fails with 403 on_device_not_authorized.
• Everything else stays the same: same signing scheme, same metric set, same measurement result — except that on-device results carry attested: false, because the client computed them.

Approval can be revoked. Revocation withdraws the entitlement to download weights; clients already holding the assets keep working until they need to fetch them again, so treat revocation as a stop on distribution rather than a kill switch.

Managing keys

• Rotate a key to issue a new secret (the old one stops working immediately). This is also the only way back from a lost secret — the console stores a hash and can never show the secret again.
• Disable a key to block it without deleting it, or delete it entirely.

How the key is used

Every SDK and API call is signed with HMAC-SHA256 over three headers — x-key-id, x-timestamp, x-signature. See API → Authentication for the signing recipe.

In the cloud tier the browser never sees the key at all: your backend signs POST /sdk/v1/cloud/sessions and passes the page a short-lived session token instead. See Cloud quickstart.

Next: Cloud quickstart, iOS installation, or Web installation.