Authentication

Learn how to use API keys to access enhanced Gravatar profile features and implement secure authentication.

Why Use Authentication?

While basic avatar display works without authentication, an API key unlocks powerful features:

Complete Profile Data

Access detailed user profiles with job titles, bios, locations, and social links

Verified Accounts

Show verified social media accounts and professional networks

Higher Rate Limits

Increased API quotas for profile fetching (1000 requests/hour)

Advanced Features

Access QR code generation and profile management features

Getting Your API Key

Step-by-Step Process

1. Log in to your Gravatar account at gravatar.com
2. Navigate to Developer Dashboard: https://gravatar.com/developers/
3. Click “Create New Application”
4. Fill in required information:
   • Application name
   • Description
   • Website URL (optional)
   • Redirect URI (for OAuth applications)
5. Save your API key securely

API Key Types

• Bearer Token: Standard API key for server-side requests
• OAuth 2.0: For applications that need user authorization
• Public Access: Limited functionality without authentication

Basic Authentication

For server-side usage, provide the API key directly to profile functions:

---
import { getProfile } from 'astro-gravatar';

const profile = await getProfile('user@example.com', {
  apiKey: 'your-api-key-here'
});
---

<GravatarProfileCard
  email={profile.email}
  layout="card"
  avatarSize={100}
  showName
  showBio
  showVerified
/>

Environment Configuration

For security, store your API key in environment variables:

.env

GRAVATAR_API_KEY=your-api-key-here

---
import { getProfile } from 'astro-gravatar';

const apiKey = import.meta.env.GRAVATAR_API_KEY;

if (!apiKey) {
  throw new Error('Gravatar API key not configured');
}

const profile = await getProfile('user@example.com', { apiKey });
---

Client-Side vs Server-Side

Server-Side (Recommended)

---
// Works on the server during build or SSR
import { getProfile, getProfiles } from 'astro-gravatar';

const profiles = await getProfiles([
  'user1@example.com',
  'user2@example.com'
], { apiKey: import.meta.env.GRAVATAR_API_KEY });
---

Client-Side

---
import GravatarProfileCard from 'astro-gravatar/GravatarProfileCard';
---

<div id="profile-container"></div>

<script>
  import { getProfile } from 'astro-gravatar';

  // Fetch client-side (not recommended for production)
  const apiKey = 'your-api-key-here';

  async function loadProfile() {
    try {
      const profile = await getProfile('user@example.com', { apiKey });
      // Render profile in the DOM
    } catch (error) {
      console.error('Failed to load profile:', error);
    }
  }

  loadProfile();
</script>

Authentication Examples

Complete Team Display

hello@automattic.com

Profile information unavailable

matt@wordpress.org

Profile information unavailable

Enhanced Profile Data

---
import { getProfile } from 'astro-gravatar';

const profile = await getProfile('user@example.com', {
  apiKey: import.meta.env.GRAVATAR_API_KEY
});
---

<GravatarProfileCard
  email={profile.email}
  layout="card"
  avatarSize={120}
  showName
  showBio
  showVerified
  showLinks
  template="detailed"
/>

Rate Limit Management

Gravatar API has rate limits. The built-in caching helps manage them:

---
import { getProfile, clearApiCache, getApiCacheStats } from 'astro-gravatar';

// Check cache stats
console.log('Cache stats:', getApiCacheStats());

// Clear cache if needed
// clearApiCache();

// Profile with automatic caching
const profile = await getProfile('user@example.com', {
  apiKey: import.meta.env.GRAVATAR_API_KEY
});
---

<GravatarProfileCard
  email={profile.email}
  layout="horizontal"
  avatarSize={80}
  showName
  showBio
/>

Error Handling

---
import { getProfile, GravatarError } from 'astro-gravatar';

let profile = null;
let error = null;

try {
  profile = await getProfile('user@example.com', {
    apiKey: import.meta.env.GRAVATAR_API_KEY
  });
} catch (err) {
  if (err instanceof GravatarError) {
    error = {
      message: err.message,
      code: err.code,
      status: err.status,
      rateLimit: err.rateLimit
    };
  } else {
    error = { message: 'Unknown error occurred' };
  }
}
---

{profile ? (
  <GravatarProfileCard
    email={profile.email}
    layout="card"
    avatarSize={100}
    showName
    showBio
  />
) : (
  <div style="padding: 2rem; background: #fee2e2; border-radius: 0.5rem; border: 1px solid #fca5a5;">
    <h3 style="margin: 0 0 0.5rem 0; color: #991b1b;">Profile Not Available</h3>
    {error && <p style="margin: 0; color: #991b1b;">{error.message}</p>}
  </div>
)}

Security Best Practices

Environment Variables

Never commit API keys to version control. Always use environment variables.

Server-Side Only

Prefer server-side profile fetching to avoid exposing API keys in client-side code.

Rate Limiting

Implement proper error handling and retry logic for rate-limited requests.

Cache Wisely

Use built-in caching to reduce API calls and improve performance.

Advanced Configuration

Custom API Client

---
import { GravatarClient } from 'astro-gravatar';

const client = new GravatarClient({
  apiKey: import.meta.env.GRAVATAR_API_KEY,
  baseUrl: 'https://api.gravatar.com/v3', // Custom base URL for proxy/CDN
  timeout: 15000, // 15 second timeout
  headers: {
    'User-Agent': 'MyApp/1.0.0'
  }
});

const profile = await client.getProfile('user@example.com');
---

<GravatarProfileCard
  email={profile.email}
  layout="card"
  avatarSize={100}
  showName
  showBio
/>

Multiple API Keys

---
const apiKeys = [
  'key1', 'key2', 'key3'
];

let profile = null;
let currentKeyIndex = 0;

for (let i = 0; i < apiKeys.length; i++) {
  try {
    profile = await getProfile('user@example.com', {
      apiKey: apiKeys[i]
    });
    break;
  } catch (error) {
    if (error.code === 'RATE_LIMITED' && i < apiKeys.length - 1) {
      continue; // Try next key
    }
    throw error;
  }
}
---

Testing with Mock Data

---
const isDevelopment = import.meta.env.DEV;

const mockProfile = {
  hash: 'mock-hash',
  display_name: 'Test User',
  avatar_url: 'https://0.gravatar.com/avatar/mock?s=100',
  description: 'This is a test profile',
  location: 'Test City',
  job_title: 'Test Engineer'
};

const profile = isDevelopment
  ? mockProfile
  : await getProfile('user@example.com', {
      apiKey: import.meta.env.GRAVATAR_API_KEY
    });
---

Common Issues

404 Errors

User might not have a Gravatar account. Use fallback avatars.

Rate Limits

Too many requests. Implement caching and retry with exponential backoff.

Invalid API Key

Check your API key format and ensure it’s correctly configured.

Next Steps

• Basic Usage - Common usage patterns
• Performance Guide - Optimize profile fetching
• Component Reference - Complete API documentation