Authentication

Pairing with a KeepKey is literally one click. The user presses Pair, approves on the device, and your app gets a bearer token it can reuse forever.

How it works under the hood

1. Your app calls KeepKeySdk.create() (or the raw REST endpoint POST /auth/pair).
2. The desktop application pops a pairing dialog with your app’s name and icon.
3. The user approves.
4. The REST API returns an API key — a bearer token your app stores.
5. All subsequent requests include Authorization: Bearer <apiKey>.

import { KeepKeySdk } from 'keepkey-vault-sdk'
 
// First run — no key, triggers pairing dialog
const sdk = await KeepKeySdk.create({
  serviceName: 'My App',
  serviceImageUrl: 'https://example.com/icon.png',
})
 
console.log(sdk.apiKey) // save this somewhere

Storing and reusing the API key

The SDK doesn’t persist the key for you — that’s your app’s job. For browser apps, localStorage is fine; for CLI tools, a file in ~/.config/ or similar; for server apps, an environment variable or secret store.

const saved = localStorage.getItem('keepkey-api-key') ?? undefined
const sdk = await KeepKeySdk.create({ apiKey: saved, serviceName: 'My App' })
 
if (sdk.apiKey && sdk.apiKey !== saved) {
  localStorage.setItem('keepkey-api-key', sdk.apiKey)
}

If the supplied key is invalid or revoked (the user rejected a re-pair, or revoked the key in the desktop app), create() will automatically trigger a new pairing dialog.

Raw REST usage

If you’re not using the TypeScript SDK, here’s the same flow with curl:

# 1. Pair — this blocks until the user approves on the device
curl -X POST http://localhost:1646/auth/pair \
  -H "Content-Type: application/json" \
  -d '{"name": "My App", "url": "https://example.com", "imageUrl": "https://example.com/icon.png"}'
 
# Response:
# { "apiKey": "eyJ..." }
 
# 2. Use the key on subsequent requests
curl http://localhost:1646/system/info/get-features \
  -X POST \
  -H "Authorization: Bearer eyJ..."

Device approval on signing

Authentication via bearer token grants the right to request signatures — it does not grant the ability to sign automatically. Every signing endpoint (/eth/sign-transaction, /utxo/sign-transaction, etc.) blocks until the user physically confirms or rejects on the KeepKey device.

Default signing timeout: 10 minutes. If the user doesn’t respond, the request returns an error and no signature is produced.

This is the core security property of the hardware wallet: a leaked API key cannot silently drain funds, because every transaction requires a physical button press.

Revoking access

Users can revoke any paired app’s API key from the desktop application’s Settings → API Servers panel at any time. Revoked keys return 401 Unauthorized on the next request, and the SDK will automatically trigger a new pairing flow.