API Authentication

Set up API keys, manage tokens, and configure secure access to the Grader.io REST API.

Overview

Secure API access is essential for protecting your lead data and ensuring only authorized systems can interact with your graders. This guide covers authentication methods, token management, and security best practices.

API Key Authentication

Getting Your API Key

1. Navigate to Settings - Dashboard → Settings → API Keys
2. Generate New Key - Click "Create API Key"
3. Set Permissions - Choose read-only or read-write access
4. Store Securely - Copy key to secure location (won't be shown again)

Using API Keys

Include your API key in the Authorization header:

curl -H "Authorization: Bearer sk_live_abc123xyz789" \
     -H "Content-Type: application/json" \
     https://api.grader.io/v1/submissions

Key Types

sk_live_

sk_test_

sk_ro_

Security Best Practices

Environment Variables

# Store in environment variables
export GRADER_API_KEY="sk_live_your_key_here"

# Use in applications
curl -H "Authorization: Bearer $GRADER_API_KEY" ...

Key Rotation

• Rotate regularly - Update keys every 90 days
• Multiple keys - Use different keys for different applications
• Revoke compromised keys - Immediately disable exposed keys
• Monitor usage - Review API key activity regularly

Rate Limiting

API requests are limited by plan:

Error Handling

Common Authentication Errors

// 401 Unauthorized - Invalid key
{
  "error": "unauthorized",
  "message": "Invalid API key"
}

// 403 Forbidden - Insufficient permissions
{
  "error": "forbidden", 
  "message": "Read-only key cannot create submissions"
}

// 429 Rate Limited
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests",
  "retry_after": 60
}

Next Steps

• Explore Submissions API to start sending data
• Set up webhooks for real-time notifications
• Review rate limits for your plan
• Configure SDK authentication for easier integration