API Authentication

Learn how to authenticate your API requests to Valgent's validation service. This guide covers API key creation, security best practices, and example implementations in multiple programming languages.

Base URL

https://api.valgent.io

Authentication

All endpoints require authentication via the Authorization header:

Authorization: Bearer vgk_your_api_key_here

Getting Your API Key

1. Sign up for a Valgent account at valgent.io/signup
2. Navigate to your API Keys dashboard
3. Click "Create New Key" and give it a descriptive name
4. Copy your API key immediately - it won't be shown again

Using Your API Key

Include your API key in the X-API-Key header with all API requests:

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

API Key Format

Valgent API keys follow a consistent format:

• vgk_* - All API keys start with vgk_ prefix

Security Best Practices

Environment Variables

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

# .env file
VALGENT_API_KEY=vgk_abc123...

// Node.js
const apiKey = process.env.VALGENT_API_KEY;

# Python
import os
api_key = os.environ.get('VALGENT_API_KEY')

Key Rotation

Rotate your API keys regularly:

1. Create a new API key in the dashboard
2. Update your application to use the new key
3. Delete the old key once confirmed working

Key Permissions

When creating API keys, follow the principle of least privilege:

• Create separate keys for different environments (dev, staging, prod)
• Use read-only keys where write access isn't needed
• Restrict keys to specific IP addresses when possible (Team plan)

Authentication Errors

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

This error occurs when:

• No API key is provided
• The API key is invalid or has been deleted
• The API key format is incorrect

403 Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have permission for this operation"
  }
}

This error occurs when:

• Rate limits have been exceeded
• Account restrictions are in place
• The request is blocked for security reasons

Example Implementations

Node.js / JavaScript

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

const result = await response.json();

Python

import requests
import os

response = requests.post(
    'https://api.valgent.io/v1/validate',
    headers={
        'Authorization': f"Bearer {os.environ.get('VALGENT_API_KEY')}",
        'Content-Type': 'application/json'
    },
    json={
        'agent_card': agent_card_data
    }
)

result = response.json()

Go

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)

func validateAgentCard(agentCard map[string]interface{}) error {
    data, _ := json.Marshal(map[string]interface{}{
        "agent_card": agentCard,
    })

    req, _ := http.NewRequest("POST", "https://api.valgent.io/v1/validate", bytes.NewBuffer(data))
    req.Header.Set("Authorization", "Bearer " + os.Getenv("VALGENT_API_KEY"))
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    // Handle response...
}