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

# Authorize

Start the OAuth 2.0 authorization code flow. Redirects the user to the consent page.

**No authentication required.** This is a public endpoint.

<RequestExample>
  ```bash cURL theme={null}
  # Redirect the user's browser to this URL
  open "https://api.v2.dealmachine.com/v1/oauth/authorize?\
  client_id=dm_cid_abc123&\
  redirect_uri=http://localhost:3000/callback&\
  response_type=code&\
  scope=account:read&\
  state=random_state_string"
  ```

  ```typescript Node.js theme={null}
  const params = new URLSearchParams({
    client_id: 'dm_cid_abc123',
    redirect_uri: 'http://localhost:3000/callback',
    response_type: 'code',
    scope: 'account:read',
    state: crypto.randomUUID(),
  });

  // Redirect user's browser
  window.location.href = `https://api.v2.dealmachine.com/v1/oauth/authorize?${params}`;
  ```
</RequestExample>

## Query Parameters

| Parameter               | Type   | Required    | Description                                     |
| ----------------------- | ------ | ----------- | ----------------------------------------------- |
| `client_id`             | string | Yes         | Your application's client ID (`dm_cid_xxx`)     |
| `redirect_uri`          | string | Yes         | Must match a registered redirect URI            |
| `response_type`         | string | Yes         | Must be `code`                                  |
| `scope`                 | string | Yes         | Space-separated scopes (e.g., `account:read`)   |
| `state`                 | string | Recommended | Random string to prevent CSRF attacks           |
| `code_challenge`        | string | No\*        | PKCE challenge (base64url-encoded SHA-256 hash) |
| `code_challenge_method` | string | No\*        | `S256` or `plain`                               |

\* Required for public (non-confidential) clients.

## Available Scopes

| Scope          | Description              |
| -------------- | ------------------------ |
| `account:read` | View account information |

## PKCE Support

For public clients, PKCE (Proof Key for Code Exchange) is required:

```typescript theme={null}
import crypto from 'crypto';

// Generate code verifier
const codeVerifier = crypto.randomBytes(32).toString('base64url');

// Generate code challenge (S256)
const codeChallenge = crypto
  .createHash('sha256')
  .update(codeVerifier)
  .digest('base64url');

// Include in authorize request
const params = new URLSearchParams({
  client_id: 'dm_cid_abc123',
  redirect_uri: 'http://localhost:3000/callback',
  response_type: 'code',
  scope: 'account:read',
  code_challenge: codeChallenge,
  code_challenge_method: 'S256',
});
```

Save the `codeVerifier` - you'll need it when exchanging the authorization code for tokens.