API Reference

Authentication

Secure your API requests with proper authentication

Overview

ParrotRouter uses API keys to authenticate requests. You can create and manage your API keys from the dashboard. All API requests must include your API key in the Authorization header.

Security Note: Your API key is sensitive. Never expose it in client-side code, commit it to version control, or share it publicly.

Getting Your API Key

Step 1: Create an Account

Create account →

Step 2: Generate API Key

Navigate to the API Keys section in your dashboard and click "Create New Key".

Go to API Keys →

Step 3: Save Your Key

Copy your API key immediately. For security reasons, we only show it once. If you lose it, you'll need to create a new one.

Using Your API Key

Include your API key in the Authorization header as a Bearer token:

cURLbash

curl https://api.parrotrouter.com/v1/chat/completions \
  -H "Authorization: Bearer pr-1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Pythonpython

from openai import OpenAI

client = OpenAI(
    base_url="https://api.parrotrouter.com/v1",
    api_key="pr-1234567890abcdef"
)

TypeScripttypescript

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.parrotrouter.com/v1',
  apiKey: 'pr-1234567890abcdef',
});

JavaScript (Fetch)javascript

const response = await fetch('https://api.parrotrouter.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pr-1234567890abcdef',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Hello!' }]
  })
});

Security Best Practices

Use Environment Variables

Never hardcode API keys in your source code. Use environment variables instead.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.parrotrouter.com/v1",
    api_key=os.getenv("PARROTROUTER_API_KEY")
)

Restrict Key Permissions

Create separate keys for different environments and applications. Revoke unused keys.

• Use read-only keys for analytics
• Create project-specific keys
• Rotate keys regularly
• Monitor key usage in dashboard

Server-Side Only

Never use API keys in client-side code. Always make API calls from your backend.

❌ Bad: Direct API calls from browser

✅ Good: Browser → Your Server → ParrotRouter API

API Key Format

ParrotRouter API keys follow a specific format for easy identification:

pr-[environment]-[random-string]

Prefix: pr- identifies this as a ParrotRouter key

Environment: live for production, test for testing

Random String: 32 character unique identifier

Example:

pr-live-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Error Responses

Authentication errors return appropriate HTTP status codes:

Missing API Key

401

{
  "error": {
    "message": "No API key provided",
    "type": "authentication_error",
    "code": "missing_api_key"
  }
}

Invalid API Key

401

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Insufficient Credits

402

{
  "error": {
    "message": "Insufficient credits. Please add credits to continue.",
    "type": "payment_required",
    "code": "insufficient_credits"
  }
}