API Keys Management

API keys provide secure access to Valgent's validation services. This guide covers creating, managing, and using API keys effectively.

Overview

API keys authenticate your requests to the Valgent API and track usage against your account. Each key can have different permissions and usage limits based on your subscription plan.

Creating API Keys

1. Navigate to API Keys Section

From the dashboard sidebar, click API Keys to access the management interface.

2. Generate a New Key

Click Create New API Key and provide a name for your key:

Name - A descriptive name to help you identify the key (e.g., "Production API Key", "Development Key", "CI/CD Pipeline")

3. Save Your Key

After creating the key, copy it immediately - it won't be shown again for security reasons. Store it securely in:

Environment variables
Secure credential management systems
CI/CD secret stores

Note: All API keys have full access to validation services. Rate limits and quotas are determined by your account plan.

Managing Existing Keys

Viewing Key Details

Each API key displays:

Name and Description - Human-readable identifiers
Created Date - When the key was generated
Last Used - Most recent API request
Usage Stats - Current month's usage
Status - Active, expired, or revoked

Key Operations

Key management operations are handled through the dashboard for security:

Regenerate Key - Create a new key and invalidate the old one
Delete Key - Permanently remove a key
View Usage - Monitor key usage and rate limits

Using API Keys

Authentication Header

Include your API key in the Authorization header:

curl -X POST https://api.valgent.io/v1/validate \
  -H "Authorization: Bearer vgk_123456789abcdef" \
  -H "Content-Type: application/json" \
  -d @agent-card.json

Environment Variables

Store keys securely in environment variables:

# .env file
VALGENT_API_KEY=vgk_123456789abcdef

# Usage in code
const response = await fetch('https://api.valgent.io/v1/validate', {
  headers: {
    'Authorization': `Bearer ${process.env.VALGENT_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(agentCard)
});

Key Format

All Valgent API keys follow a consistent format:

vgk_1234567890abcdef1234567890abcdef

Security Best Practices

✅ Do

Store keys in environment variables
Use different keys for different environments
Rotate keys regularly (every 90 days)
Monitor key usage regularly
Revoke unused or compromised keys immediately

❌ Don't

Commit keys to version control
Share keys via email or chat
Use production keys in development
Embed keys in client-side code
Reuse the same key across multiple applications

Troubleshooting

Common Issues

401 Unauthorized

{
  "error": "invalid_key",
  "message": "The provided API key is invalid or expired"
}

Solution: Check that your key is correct and hasn't expired.

403 Forbidden

{
  "error": "forbidden",
  "message": "Access denied"
}

Solution: This usually indicates rate limit exceeded or account-related restrictions. Check your usage limits and account status.

429 Rate Limited

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please try again later."
}

Solution: Implement exponential backoff or upgrade your plan for higher limits.

Usage Monitoring

Dashboard Analytics

Monitor key usage through the dashboard:

Request Volume - Daily/monthly request counts
Error Rates - Percentage of failed requests
Response Times - API performance metrics
Geographic Distribution - Request origins

Alerts and Notifications

Set up alerts for:

Approaching rate limits
Unusual usage patterns
Key expiration warnings
Failed authentication attempts

Usage Reports

Export detailed usage reports:

CSV format for spreadsheet analysis
JSON format for programmatic processing
Email delivery options available

Team Key Management

Shared Keys

For team environments:

Create keys with team-specific permissions
Use descriptive names and documentation
Implement key rotation policies
Monitor usage across team members

Individual Keys

For personal development:

Create keys tied to individual accounts
Name keys descriptively for easy identification
Set up personal usage alerts
Regularly review and clean up unused keys