Authentication

All API requests require authentication using an API key.

Getting Your API Key

To get started with the Nameday API, you'll need to obtain an API key:

1. Visit the API Dashboard
2. Sign in with your email or create a free account
3. Your API key will be automatically generated and displayed on the dashboard
4. Copy the key and keep it secure

API Key Format

Nameday API keys follow a standardized format for easy identification:

nd_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

All API keys begin with nd_live_ followed by 32 hexadecimal characters. This prefix helps prevent accidental exposure in logs or monitoring tools.

Using Your API Key

Include your API key in the x-api-key header of every request:

x-api-key: nd_live_your_key_here

Example Request

curl -X GET 'https://name.birrday.com/api/v1/namedays?country=GR' \
  -H 'x-api-key: nd_live_your_key_here'

Using with JavaScript/TypeScript

const response = await fetch('https://name.birrday.com/api/v1/namedays?country=GR', {
  headers: {
    'x-api-key': 'nd_live_your_key_here'
  }
});

const data = await response.json();

// Check rate limit status
const remaining = response.headers.get('X-RateLimit-Remaining');
console.log(`Requests remaining: ${remaining}`);

Using with Python

import requests

headers = {
    'x-api-key': 'nd_live_your_key_here'
}

response = requests.get(
    'https://name.birrday.com/api/v1/namedays',
    params={'country': 'GR'},
    headers=headers
)

data = response.json()

# Check rate limit status
remaining = response.headers.get('X-RateLimit-Remaining')
print(f'Requests remaining: {remaining}')

Rate Limits & Quotas

The Nameday API enforces rate limits to ensure fair usage and system stability. Every API response includes headers with your current status:

Response Headers

Every API response includes headers to help you track your usage:

What Happens When Limits Are Exceeded?

When you exceed your rate limit or monthly quota, the API will return an error response:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704643200
Retry-After: 60

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Retry after 60 seconds.",
  "statusCode": 429
}

For free tier users who have exceeded their monthly quota, you'll receive a 402 Payment Required response. You can upgrade to a paid plan to continue using the API.

For detailed information about pricing and rate limits, see the Rate Limits & Pricing documentation.

Error Responses

Authentication and authorization errors return standard HTTP status codes:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key",
  "statusCode": 401
}

{
  "error": "Payment Required",
  "message": "Monthly quota exceeded. Please upgrade your plan.",
  "statusCode": 402
}

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Retry after 60 seconds.",
  "statusCode": 429
}

Security Best Practices

Environment Variables

Store your API key in environment variables, never hardcode it in your source code:

# .env file (add to .gitignore!)
NAMEDAY_API_KEY=nd_live_your_key_here

# In your code
const apiKey = process.env.NAMEDAY_API_KEY;

fetch('https://name.birrday.com/api/v1/namedays', {
  headers: { 'x-api-key': apiKey }
});

Key Rotation

Rotate your API keys periodically or immediately if you suspect they've been compromised:

1. Generate a new API key in the dashboard
2. Update your application to use the new key
3. Test that the new key works correctly
4. Revoke the old key from the dashboard

Additional Security Guidelines

• Use HTTPS: Always use HTTPS when making API requests to protect your key in transit
• Server-Side Only: Make API calls from your backend, not from browsers or mobile apps
• Limit Permissions: Use separate API keys for development, staging, and production
• Version Control: Add .env files to .gitignore to prevent accidental commits
• Access Control: Only share API keys with team members who need them