# Require Touch ID or a passkey for the CLI

Require people to sign in to the CLI with Touch ID or a passkey, and refuse people's own access keys, or only old ones.

The organization's CLI sign-in policy has two parts. **Require Touch ID or a passkey** applies to
people's CLI sessions and to the apps they connect (AI assistants over MCP). **People's own access
keys** refuses the access keys of people (members, and IAM users with console access), all of them
or those older than a number of days. Service accounts, OIDC role sessions and the console sign-in
are never affected, so nobody is locked out of the console.

**Important:**
Refusing people's access keys stops every script and tool that uses one. Preview the change first,
and give automation a service account's key or OIDC before you save.

## Prerequisites

- `iam:GetCliAuthPolicy` to see the policy and preview a change. Without it, **Command line sign-in**
  is not shown on the **Organization settings** page.
- `iam:UpdateCliAuthPolicy` to change it. Without it, the console shows the settings but not to
  change: `Changing it needs the iam:UpdateCliAuthPolicy permission.`
- You change it as a person, in the console with a passkey on your account (without one, saving
  says `Your account has no passkey yet`), or from a CLI session confirmed in the last five
  minutes; an access key is refused with
  403 `A person changes this from the console or a CLI session, not with an access key`.
- To turn the requirement on, a passkey or an enrolled device (Touch ID, a security key, Windows
  Hello) on your own account; otherwise 409
  `Add a passkey (or enrol a Mac with Touch ID) to your own account first, so the requirement cannot lock you out.`

## Set the policy

**Console**
1. Open [Organization settings](/settings) and go to **Command line sign-in**.
2. (Optional) Turn on **Require Touch ID or a passkey**.
3. Under **People's own access keys**, choose **Allowed (no limit)**, **Refused**, or
   **Refused when older than** and enter a number of days from 1 to 3650.
4. Choose **Preview who is affected**. Under **If you save this**, the console lists the people who
   have neither a passkey nor a Touch ID or security-key device, the personal access keys that are
   refused (with their age and last use), how many apps were connected without a passkey and would
   stop, how many CLI sessions stop working, and how many service-account keys are unaffected, with
   any warnings.
5. Choose **Save with passkey** and confirm with your passkey.

The console says **Saved. It applies from the next request.**

**CLI**
Preview, then save, from a CLI session (`dcloud login`). When your last confirmation is more than
five minutes old, the CLI asks for your device key or your passkey before it saves.

```sh
dcloud iam cli-auth-policy get
dcloud iam cli-auth-policy dry-run --require-passkey-cli --personal-key-max-age-days 90
dcloud iam cli-auth-policy update --require-passkey-cli --personal-key-max-age-days 90
```

**API**
Send the request with a CLI session's token (`dcloud auth token`) confirmed in the last five
minutes. `personalKeyMaxAgeDays` is `null` for no limit, `0` to refuse every personal key, or the
number of days.

```http
PUT /iam/api/cli-auth-policy
{ "requirePasskeyCli": true, "personalKeyMaxAgeDays": 90 }
```

`POST /iam/api/cli-auth-policy/dry-run` with the same body answers the preview and changes nothing.
Its `unverifiedApps` counts the connected apps that would stop.

## Result

With **Require Touch ID or a passkey** on:

- `dcloud login` must be approved with a device key that verifies the person (Touch ID, a security
  key with a PIN, Windows Hello, each enrolled with a passkey) or a passkey. Otherwise 403
  `Your organization requires Touch ID or a passkey to sign in to the CLI.`, and the page
  [Approve a device](/activate) offers no approval without a passkey.
- A CLI session that was opened without one stops at its next request with 403
  `This CLI session was opened without Touch ID or a passkey, and your organization now requires one. …`
- Every person's CLI session confirms sensitive commands once their confirmation window has passed
  (see [Confirm sensitive CLI commands](confirm-sensitive-cli-commands.md)), whatever their own
  setting. **Longest a confirmation may last** caps the window everyone can choose (no cap: 60 minutes).
- Connecting an app to the organization (an AI assistant over MCP) needs a passkey: the consent
  screen's button is **Allow with passkey**. For a person without a passkey, the screen says
  `… requires a passkey to connect an app, and your account has none yet. …`, and choosing
  **Allow with passkey** shows `Your account has no passkey yet`. The API refuses a consent without
  a passkey with 403 `… requires a passkey to connect an app. Confirm with your passkey.` An app
  connected without one stops at its next request with 403
  `This app was connected without a passkey, and … now requires one. Connect it again.`
- An older dcloud that signs in with a 90-day access key is refused with 403
  `This version of … signs in with a 90-day access key, which your organization or your account no longer allows. …`

With **People's own access keys** limited, a refused key is answered 403 with the code
`PERSONAL_KEY_REFUSED` and `Your organization does not accept personal access keys. …` or
`Your organization refuses personal access keys older than 90 days, and this one is older. …`.
A refusal is recorded in the audit log as `auth:PersonalAccessKeyRefused`, at most once a minute
per key. A key with a scope policy is never refused; the preview still lists it.

## Related

- [Sign in the CLI](sign-in-the-cli.md)
- [Confirm sensitive CLI commands](confirm-sensitive-cli-commands.md)
- [Manage a member's CLI devices](manage-a-members-cli-devices.md)
- [Create an access key](create-an-access-key.md)
- [Policy documents](policy-documents.md): the condition keys `dcloud:AuthMethod`,
  `dcloud:PrincipalType`, `dcloud:UserVerified` and `dcloud:UserVerifiedAge` express such
  rules per action.
