# /docs/authentication

import PairDemo from '@/components/PairDemo'

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

<PairDemo />

## 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>`.

```ts
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.

```ts
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`:

```bash
# 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](/docs/desktop/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.