API Onboarding

// Track these events with timestamps
analytics.track('docs_quickstart_viewed');
analytics.track('signup_started');
analytics.track('signup_completed');
analytics.track('api_key_created');
analytics.track('sdk_installed');     // Via package manager data
analytics.track('first_api_call');    // Via API logs
analytics.track('first_successful_call');

❌ "Your API access request has been submitted.
    You'll receive access within 2-3 business days."

❌ Settings → Team → API → Credentials → Keys → Show Key

❌ OAuth flow requiring:
   - Client ID
   - Client secret
   - Redirect URI configuration
   - Token exchange
   - Token refresh handling

❌ Sign up → Verify email → Verify phone →
   Add payment → Verify payment → Then API key

✅ "Here's your test API key: sk_test_abc123...
    Use this in sandbox mode—no charges, no setup."

✅ Quickstart: API key header
   Production: OAuth when they need it

✅ # Your API key is pre-filled in these examples
   curl -H "Authorization: Bearer sk_test_YOUR_KEY" ...

✅ Test mode: Instant access
   Production mode: Add payment, verify identity (later)

Production: api.example.com
Sandbox:    sandbox-api.example.com

Production key: sk_live_abc123...
Sandbox key:    sk_test_xyz789...

curl -X POST https://api.example.com/v1/messages \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"sandbox": true, ...}'

// Sandbox comes with test users
const testUsers = await client.users.list();
// Returns: [
//   { id: "usr_test_alice", name: "Alice (Test)" },
//   { id: "usr_test_bob", name: "Bob (Test)" }
// ]

// Special values trigger specific behaviors
client.payments.create({
  amount: 1000,
  card: "4242424242424242"  // Always succeeds
});

client.payments.create({
  amount: 1000,
  card: "4000000000000002"  // Always declines
});

## Test Card Numbers

| Number           | Behavior              |
|-----------------|----------------------|
| 4242424242424242 | Successful charge    |
| 4000000000000002 | Declined             |
| 4000000000009995 | Insufficient funds   |
| 4000000000000069 | Expired card         |

<div class="api-explorer">
  <h3>Try it: Send a Message</h3>

  <div class="request-editor">
    <label>To Phone Number</label>
    <input type="text" value="+15551234567" />

    <label>Message Body</label>
    <textarea>Hello from the API Explorer!</textarea>

    <button onclick="sendRequest()">Send Request</button>
  </div>

  <div class="response-viewer">
    <h4>Response</h4>
    <pre><code id="response"></code></pre>
  </div>
</div>

## Interactive Tutorial: Send Your First Message

### Step 1: Check your balance
<api-explorer endpoint="GET /account/balance" />

### Step 2: Send a message
<api-explorer endpoint="POST /messages"
  body='{"to": "+15551234567", "body": "Hello!"}' />

### Step 3: Check message status
<api-explorer endpoint="GET /messages/{id}"
  params='{"id": "{{previous.id}}"}' />

// Instrument error events
api.on('request_error', (error, request) => {
  analytics.track('api_error', {
    error_type: error.type,
    error_code: error.code,
    endpoint: request.endpoint,
    time_since_signup: timeSinceSignup(),
    is_first_call: isFirstCall()
  });
});

Problem: Wrong key, malformed header, missing auth
Fix:
- Clearer error messages: "API key should start with 'sk_test_'"
- Pre-filled code examples with actual key
- Auth header format shown with example

Problem: Wrong content type, malformed JSON, missing fields
Fix:
- Accept flexible content types on simple endpoints
- Return specific field-level errors
- Show exactly what was expected vs. received

Problem: SDK not installed, wrong SDK version, missing dependencies
Fix:
- Version-specific installation instructions
- Compatibility matrix clearly visible
- Quick environment check script

Problem: Aggressive rate limits during exploration
Fix:
- Generous sandbox limits (or none)
- Clear rate limit errors with retry-after
- Don't count failed requests against limits

Problem: Firewall, proxy, SSL issues
Fix:
- Connectivity test endpoint
- Clear networking troubleshooting guide
- Alternative ports/protocols if possible