api-onboarding — Claude Code skill: shorten the path to your first API call

---
name: api-onboarding
description: |
  Reduce time-to-first-API-call (TTFAC) by optimizing every step of the developer onboarding journey. This skill covers authentication simplification, sandbox environments, interactive documentation, and identifying and eliminating common failure points.

  Trigger phrases: "API onboarding", "time to first API call", "TTFAC", "developer onboarding", "first API call", "auth simplification", "sandbox environment", "interactive docs", "try it now", "API playground", "developer activation", "onboarding friction"
metadata:
  version: 1.0.0
---

# Reducing Time-to-First-API-Call

The time between a developer discovering your API and successfully making their first call is the most critical window in your entire developer journey. Every minute of friction here costs you potential users.

## Overview

Time-to-First-API-Call (TTFAC) is the single most predictive metric for developer adoption. Developers who succeed quickly become active users. Developers who struggle leave—often silently.

This skill covers:
- Measuring and optimizing TTFAC
- Removing authentication friction
- Creating effective sandbox environments
- Building interactive documentation
- Identifying and fixing common failure points

## Before You Start

Review the **developer-audience-context** skill to understand:
- What's the typical technical sophistication of your developers?
- What tools and environments do they commonly use?
- What alternative products have they tried? What was their experience?
- What's their urgency level? (Evaluating vs. building immediately)

Your onboarding should meet developers where they are.

## Understanding TTFAC

### What TTFAC Measures

Time-to-First-API-Call measures the elapsed time from a developer's first interaction to their first successful API response. This includes:

1. **Discovery time**: Finding the "Get Started" content
2. **Signup time**: Creating an account
3. **Credential time**: Obtaining API keys
4. **Setup time**: Installing SDK, configuring environment
5. **Execution time**: Running first request
6. **Success time**: Receiving successful response

### TTFAC Benchmarks

| Rating | TTFAC | Developer Experience |
|--------|-------|---------------------|
| **Excellent** | < 5 min | "This is amazing" |
| **Good** | 5-15 min | "Pretty straightforward" |
| **Acceptable** | 15-30 min | "Got there eventually" |
| **Poor** | 30-60 min | "This is frustrating" |
| **Failing** | > 60 min | "I'll try something else" |

### Measuring TTFAC

**Instrumentation points:**
```javascript
// 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');
```

**Calculate:**
- Median TTFAC (more useful than average)
- TTFAC by developer segment
- Drop-off rates at each step
- Success rates within time windows (5 min, 15 min, 60 min)

## Authentication Simplification

Authentication is the #1 source of onboarding friction. Simplify ruthlessly.

### The Ideal Auth Flow

1. Developer signs up (< 2 minutes)
2. API key visible immediately (not buried in settings)
3. Key works immediately (no activation delay)
4. Copy-paste into example code
5. Success

### Auth Anti-Patterns to Avoid

**The Approval Queue**
```
❌ "Your API access request has been submitted.
    You'll receive access within 2-3 business days."
```
Developers leave and find an alternative.

**The Hidden Key**
```
❌ Settings → Team → API → Credentials → Keys → Show Key
```
Make keys visible on dashboard home.

**The Complex Token**
```
❌ OAuth flow requiring:
   - Client ID
   - Client secret
   - Redirect URI configuration
   - Token exchange
   - Token refresh handling
```
For getting started, provide simple API keys.

**The Verification Gauntlet**
```
❌ Sign up → Verify email → Verify phone →
   Add payment → Verify payment → Then API key
```
Minimize friction for first API call.

### Auth Simplification Strategies

**Provide Test Keys Immediately**
```
✅ "Here's your test API key: sk_test_abc123...
    Use this in sandbox mode—no charges, no setup."
```

**Support Multiple Auth Methods**
```
✅ Quickstart: API key header
   Production: OAuth when they need it
```

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

**Delay Production Requirements**
```
✅ Test mode: Instant access
   Production mode: Add payment, verify identity (later)
```

## Sandbox Environments

A sandbox removes the fear of "breaking something" and lets developers experiment freely.

### Sandbox Requirements

**Instant Access**: No approval, no payment, no complex setup

**Realistic Behavior**: Same API, same responses, same errors

**Clear Boundaries**: Obvious when in sandbox vs. production

**Reset Capability**: Easy way to start fresh

**Generous Limits**: Don't rate-limit experimentation

### Sandbox Implementation Patterns

**Separate Endpoints**
```
Production: api.example.com
Sandbox:    sandbox-api.example.com
```

**Key Prefixes**
```
Production key: sk_live_abc123...
Sandbox key:    sk_test_xyz789...
```

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

### Sandbox Data

**Pre-populated Test Data**
```javascript
// 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)" }
// ]
```

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

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

**Documented Test Scenarios**
```markdown
## Test Card Numbers

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

## Interactive Documentation

Let developers make API calls without leaving the browser.

### "Try It" Functionality

**Essential Features:**
- Pre-authenticated (use their sandbox key automatically)
- Pre-filled with working example data
- Editable request parameters
- Real API responses (not mocked)
- Copy as cURL/code option

**Implementation:**
```html
<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 Docs Tools

**OpenAPI-Based:**
- Swagger UI
- Redoc
- Stoplight Elements

**Custom Platforms:**
- ReadMe.io
- Postman Published Docs
- Custom React components

### Interactive Examples

Go beyond single requests:

```markdown
## 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}}"}' />
```

## Common Failure Points

### Failure Point Analysis

Track where developers fail and why:

```javascript
// 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()
  });
});
```

### Most Common First-Call Failures

**1. Authentication Errors (40% of first-call failures)**
```
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
```

**2. Request Format Errors (25%)**
```
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
```

**3. Environment/Setup Errors (20%)**
```
Problem: SDK not installed, wrong SDK version, missing dependencies
Fix:
- Version-specific installation instructions
- Compatibility matrix clearly visible
- Quick environment check script
```

**4. Rate Limiting (10%)**
```
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
```

**5. Networking Errors (5%)**
```
Problem: Firewall, proxy, SSL issues
Fix:
- Connectivity test endpoint
- Clear networking troubleshooting guide
- Alternative ports/protocols if possible
```

### Error Recovery Flows

Design error messages that recover the onboarding:

```json
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided",
    "code": "invalid_api_key",
    "recovery": {
      "steps": [
        "Check that your API key starts with 'sk_test_' or 'sk_live_'",
        "Ensure there are no extra spaces or newlines",
        "Generate a new key at https://dashboard.example.com/keys"
      ],
      "docs": "https://docs.example.com/authentication",
      "support": "https://support.example.com/auth-issues"
    }
  }
}
```

## The First-Call Experience Audit

### Audit Checklist

Perform this audit quarterly (or after any onboarding changes):

**As a New Developer:**
- [ ] Create a new account (use a fresh browser/incognito)
- [ ] Time how long until you have a working API key
- [ ] Follow the quickstart exactly as written
- [ ] Make your first API call
- [ ] Record total time and every friction point

**Questions to Answer:**
- How many clicks from homepage to first API call?
- How many pages/tabs did you need open?
- What did you have to figure out that wasn't explained?
- Where did you get stuck or confused?
- What would have made you give up?

### Friction Point Scoring

| Friction | Impact | Priority |
|----------|--------|----------|
| Must verify email before API key | High | Fix immediately |
| API key buried in settings | High | Fix immediately |
| No copy button on code examples | Medium | Fix this quarter |
| Quickstart assumes specific OS | Medium | Fix this quarter |
| Example uses outdated SDK version | Low | Fix when updating docs |

## Onboarding Optimization Framework

### Step 1: Measure Current State
- Instrument TTFAC tracking
- Run first-call audit with 5 developers
- Identify top 3 drop-off points

### Step 2: Reduce Steps
- Can any step be eliminated entirely?
- Can any step be deferred until later?
- Can multiple steps be combined?

### Step 3: Accelerate Remaining Steps
- Pre-fill everything possible
- Provide copy buttons everywhere
- Show progress and next steps

### Step 4: Recover Failures
- Improve error messages
- Add inline troubleshooting
- Provide live support for stuck developers

### Step 5: Measure and Iterate
- Track TTFAC improvements
- A/B test onboarding changes
- Regular audits with real developers

## Tools

### Onboarding Analytics
- **Amplitude/Mixpanel**: Event tracking and funnels
- **FullStory/Hotjar**: Session recording
- **Custom dashboards**: TTFAC metrics

### Interactive Docs
- **ReadMe.io**: Full-featured developer hub
- **Stoplight**: OpenAPI-powered docs
- **Redocly**: API documentation platform
- **Custom**: Build with React/Vue

### Testing
- **Ghost Inspector**: Automated onboarding testing
- **Checkly**: API monitoring and testing
- **k6**: Load testing of onboarding flows

## Related Skills

- **docs-as-marketing**: Quickstart documentation
- **sdk-dx**: SDK that reduces onboarding complexity
- **developer-sandbox**: The playground developers onboard with
- **developer-audience-context**: Understanding your onboarding audience
- **developer-metrics**: Measuring onboarding success