Authentication

Learn how to authenticate with the Nellie API and manage your API keys securely.

Base URL: https://api.nelliewriter.com/v1

Overview

The Nellie API uses API keys for authentication. Every request to authenticated endpoints must include your API key in the X-API-Key header.

Getting Your API Key

Step 1: Access the Developer Console

1. Open the Nellie mobile app
2. Navigate to Settings → API Management
3. Or visit https://app.nelliewriter.com/api on web

Step 2: Create a New Key

1. Select the API Keys tab
2. Tap “Create Key”
3. Give it a descriptive name (e.g., “Production Server”, “Development”, “CI/CD Pipeline”)
4. Copy the key immediately — it will only be shown once!

Your API key will look like:

nel_abc123def456ghi789jkl012mno345pqr678

Using Your API Key

Include your API key in the X-API-Key header of every request:

cURL

curl -X POST https://api.nelliewriter.com/v1/book \
  -H "X-API-Key: nel_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A mystery novel"}'

Python (with SDK)

from nellie_api import Nellie

# Option 1: Pass directly
client = Nellie(api_key="nel_your_api_key_here")

# Option 2: Use environment variable (recommended)
# Set NELLIE_API_KEY in your environment, then:
client = Nellie()

Python (with requests)

import requests

headers = {
    "X-API-Key": "nel_your_api_key_here",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.nelliewriter.com/v1/book",
    headers=headers,
    json={"prompt": "A mystery novel"}
)

JavaScript/Node.js

const response = await fetch('https://api.nelliewriter.com/v1/book', {
  method: 'POST',
  headers: {
    'X-API-Key': 'nel_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ prompt: 'A mystery novel' })
});

Environment Variables

We strongly recommend storing your API key in environment variables or cloud secrets rather than hardcoding it:

Setting Environment Variables

Linux/macOS:

export NELLIE_API_KEY="nel_your_api_key_here"

Windows (PowerShell):

$env:NELLIE_API_KEY = "nel_your_api_key_here"

In a .env file:

NELLIE_API_KEY=nel_your_api_key_here

Reading in Your Application

Python:

import os
api_key = os.environ.get("NELLIE_API_KEY")

Node.js:

const apiKey = process.env.NELLIE_API_KEY;

Authentication Errors

When authentication fails, the API returns a 401 Unauthorized response:

{
  "success": false,
  "error": "Unauthorized",
  "details": "Valid API key required",
  "errorCode": "AUTH_REQUIRED"
}

Common Causes

Security Best Practices

✅ DO

1. Store keys in environment variables — Never hardcode keys in source code
2. Use server-side code — Make API calls from your backend, not client-side JavaScript
3. Rotate keys regularly — Create new keys periodically and revoke old ones
4. Use separate keys per environment — Have different keys for development, staging, and production
5. Monitor usage — Check the Usage endpoint or check in the Nellie API dashboard regularly for unexpected activity
6. Revoke compromised keys immediately — If a key is exposed, revoke it and create a new one

❌ DON’T

1. Commit keys to git — You SHOULD add .env to your .gitignore
2. Share keys in chat/email — Use secure methods to share credentials
3. Embed keys in client-side code — Browser JavaScript exposes your key to users
4. Use production keys for testing — Create separate development keys
5. Log API keys — Ensure your logging doesn’t capture the X-API-Key header

Key Management

Viewing Your Keys

1. Go to Settings (User icon) → API Management → API Keys, or https://app.nelliewriter.com/api → API Keys
2. You’ll see a list of your active keys with:
   • Key name
   • Created date
   • Last used date
   • Partial key preview (first/last characters)

Revoking a Key

1. Go to Settings (User icon) → API Management → API Keys, or https://app.nelliewriter.com/api → API Keys
2. Find the key you want to revoke
3. Tap “Revoke” or the delete icon
4. Confirm the action

⚠️ Warning: Revoking a key is immediate and permanent. Any applications using that key will stop working until you update it with your new key value.

Key Rotation Strategy

For production applications, we recommend:

1. Create a new key before rotating
2. Update your application to use the new key
3. Deploy the update and verify it works
4. Revoke the old key after confirming the new one works

This ensures zero downtime during rotation.

Webhook Secrets

For webhook signature verification, you’ll also need a Webhook Signing Secret:

1. Go to Settings (User icon) → API Management → Webhooks, or https://app.nelliewriter.com/api → Webhooks
2. Copy your Webhook Signing Secret

Your webhook secret looks like:

whsec_abc123def456...

See Webhooks for details on using your webhook secret.

Authenticated vs. Public Endpoints

Rate Limits

API keys are subject to rate limits:

• Minimum spacing: 1 request every 6 seconds
• Daily limit: 15 requests per day

See Rate Limits for complete details.

Related Documentation

• Quick Start Guide — Get started in 5 minutes
• Webhooks — Set up webhook notifications
• Errors — Handle authentication errors
• SDK Reference — Use the Python SDK