> ## Documentation Index
> Fetch the complete documentation index at: https://api.docs.dealmachine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authentication details, credential storage, and troubleshooting

# Authentication

The CLI uses the **OAuth device authorization flow** (RFC 8628) — the same pattern used by the GitHub CLI. No passwords are entered in the terminal.

## How the Device Flow Works

```mermaid theme={null}
sequenceDiagram
    participant CLI as dm CLI
    participant API as DealMachine API
    participant Browser as Your Browser

    CLI->>API: Request device code
    API-->>CLI: Device code + user code (XXXX-XXXX)
    CLI->>Browser: Open authorization page
    Note over Browser: User signs in & approves
    Browser->>API: Approve device
    CLI->>API: Poll for token
    API-->>CLI: API key
    Note over CLI: Stored at ~/.dealmachine/config.json
```

## Direct API Key Login

If you already have an API key (e.g., for CI/CD or scripts), skip the browser flow:

```bash theme={null}
dm login --key dm_sk_live_xxxxx
```

This verifies the key against the API and saves it locally.

If you do not have an API key yet, use the public API onboarding flow first:

1. `dm signup developer@example.com --login` creates the account, returns an API key, and stores it locally. Add `--phone-number +15551234567` if the API environment requires phone numbers.
2. `dm plans` lists public self-serve Basic and Pro plan prices.
3. `dm checkout --price-id price_xxx_monthly` creates a Stripe checkout session with that API key.

You can also call `POST /v1/signup`, `GET /v1/plans`, and `POST /v1/checkout` directly.

## Logout

```bash theme={null}
dm logout
```

Removes stored credentials from `~/.dealmachine/config.json`.

## Check Auth Status

```bash theme={null}
dm whoami
```

```
Current authentication:

  Organization: My Company (my-company)
  Org ID:       1
  API Key:      dm_sk_live_VMgXKyJQ...
  Key ID:       key_abc123def456

Config file: /Users/you/.dealmachine/config.json
```

Use `--verify` to test your key against the server:

```bash theme={null}
dm whoami --verify
```

## Credential Storage

Credentials are stored at:

```
~/.dealmachine/config.json
```

The file has `0600` permissions (owner-only read/write) and contains:

```json theme={null}
{
  "apiKey": "dm_sk_live_xxx",
  "keyId": "key_abc123",
  "organizationId": 1,
  "organizationName": "My Company",
  "organizationSlug": "my-company"
}
```

<Warning>
  Never share your `config.json` file or commit it to version control. The API key provides full access to your organization's data.
</Warning>

## Revoking Access

To revoke a CLI key:

1. Go to [Developer Settings](https://dm-next.dealmachine.com/settings/developer)
2. Find the key (named "CLI" or the device name)
3. Click **Revoke**

After revoking, run `dm logout` to clean up local credentials, then `dm login` to re-authenticate.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Browser doesn't open automatically">
    Use the `--no-browser` flag and manually visit the URL:

    ```bash theme={null}
    dm login --no-browser
    ```
  </Accordion>

  <Accordion title="Code expired">
    Device codes expire after 30 days. Run `dm login` again to get a fresh code.
  </Accordion>

  <Accordion title="Wrong organization">
    Run `dm logout` first, then `dm login` again. Make sure you select the correct organization in the browser.
  </Accordion>

  <Accordion title="Invalid credentials">
    Your key may have been revoked. Run:

    ```bash theme={null}
    dm whoami --verify
    ```

    If it fails, run `dm logout && dm login` to re-authenticate.
  </Accordion>
</AccordionGroup>