# useDeviceApproval

<!-- https://uncage.vercel.app/docs/api/react/functions/usedeviceapproval/ -->

```ts
function useDeviceApproval(code, options?): object;
```

Defined in: react/src/hooks.ts:504

Headless device approval (connected mode): looks the code up, then approves or denies it.

| `state` | meaning | what you can do |
| --- | --- | --- |
| `'loading'` | the lookup is in flight | wait |
| `'idle'` | `lookup` is set; also after a failed decision (`error` set) | `approve()` / `deny()` |
| `'approving'` / `'denying'` | the decision is in flight | wait (further calls are ignored) |
| `'approved'` / `'denied'` | done | nothing (final) |
| `'not_found'` | the code is unknown (lookup returned `null`, or the decision said so) | ask for a new code |
| `'expired'` | the code is too old | ask for a new code |
| `'error'` | the lookup failed (e.g. `rate_limited`, network); `error` is set | `retry()` |

`approve` / `deny` only act from `'idle'` (no double submit); `retry` only acts from `'error'`.
Changing `code` starts over at `'loading'`.

**Codes from links** (`source: 'link'`, the default): `approve()` does nothing until the user has
typed the code's last 4 characters (`confirmation.setTyped`, checked by `confirmation.matched`).
Show a warning ("Only approve if you just ran `uncage setup` on a computer in front of you. Never
approve a code someone sent you."), `lookup.requestedAt` and `lookup.requestIp` next to it. Pass
`source: 'typed'` only when the user typed the whole code themselves. `deny()` never needs it.
A link code that is not exactly `ABCD-EFGH` / `ABCDEFGH` is not looked up: `state` is
`'not_found'` and `linkInvalid` is `true` (show "this link is not valid" and the manual entry).

## Parameters

| Parameter | Type |
| ------ | ------ |
| `code` | `string` |
| `options?` | \{ `source?`: [`DeviceCodeSource`](https://uncage.vercel.app/docs/api/react/type-aliases/devicecodesource.md); \} |
| `options.source?` | [`DeviceCodeSource`](https://uncage.vercel.app/docs/api/react/type-aliases/devicecodesource.md) |

## Returns

| Name | Type | Description | Defined in |
| ------ | ------ | ------ | ------ |
| `confirmation` | `object` | Type-to-confirm for codes from links. `required`: `source` is `'link'`. `typed`: what the user typed so far. `matched`: it equals the code's last 4 characters (always `true` when not required). | react/src/hooks.ts:515 |
| `confirmation.matched` | `boolean` | - | react/src/hooks.ts:515 |
| `confirmation.required` | `boolean` | - | react/src/hooks.ts:515 |
| `confirmation.typed` | `string` | - | react/src/hooks.ts:515 |
| `confirmation.setTyped()` | (`value`) => `void` | - | react/src/hooks.ts:515 |
| `error?` | `object` | - | react/src/hooks.ts:510 |
| `error.code` | `string` | - | react/src/hooks.ts:510 |
| `error.message` | `string` | - | react/src/hooks.ts:510 |
| `linkInvalid` | `boolean` | A link-sourced code with the wrong shape: it was not looked up and cannot be approved. | react/src/hooks.ts:517 |
| `lookup` | [`DeviceLookup`](https://uncage.vercel.app/docs/api/react/interfaces/devicelookup.md) \| `null` | - | react/src/hooks.ts:508 |
| `state` | [`DeviceApprovalState`](https://uncage.vercel.app/docs/api/react/type-aliases/deviceapprovalstate.md) | - | react/src/hooks.ts:509 |
| `approve()` | () => `Promise`\<`void`\> | - | react/src/hooks.ts:518 |
| `deny()` | () => `Promise`\<`void`\> | - | react/src/hooks.ts:519 |
| `retry()` | () => `void` | Re-runs a failed lookup (only from `'error'`). | react/src/hooks.ts:521 |
