Authentication

Forest SEO API uses API Key authentication to secure all API requests. This guide explains how to create, manage, and use API keys for programmatic access.

🔑 Authentication Method

All API requests must include an API key in the Authorization header using the following format:

Authorization: API-Key YOUR_API_KEY_HERE

📋 API Key Overview

What Are API Keys?

API keys are 64-character tokens that authenticate your application or integration with Forest SEO's backend services. Each API key:

• Associates with a user account — operates with that user's permissions
• Can be disabled — temporarily revoke access without deletion
• Has a specific purpose — track usage by integration type
• Is auto-generated — cryptographically secure random strings

Key Properties

🚀 Creating an API Key

Example: "Production CMS Integration"

Example: "Used by WordPress plugin to auto-publish generated articles to https://myblog.com"

🔧 Using API Keys

HTTP Request Headers

Include your API key in every request to the Forest SEO API:

curl -X GET "https://api.forestseo.com/v1/projects" \
  -H "Authorization: API-Key YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json"

Example: List Projects

curl -X GET "https://api.forestseo.com/v1/projects" \
  -H "Authorization: API-Key Abc123...xyz789"

Response:

{
  "items": [
    {
      "id": "proj_abc123",
      "name": "My Blog",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "total": 1
}

Project Context Header

Most API endpoints require a project context. Include the X-Project-ID header:

curl -X GET "https://api.forestseo.com/v1/contents" \
  -H "Authorization: API-Key YOUR_API_KEY_HERE" \
  -H "X-Project-ID: proj_abc123" \
  -H "Content-Type: application/json"

🛡️ Security Best Practices

Environment Variables

Store API keys in environment variables:

Development (.env.local):

FORESTSEO_API_KEY=YOUR_API_KEY_HERE
FORESTSEO_PROJECT_ID=proj_abc123

Usage in code:

const apiKey = process.env.FORESTSEO_API_KEY;
const projectId = process.env.FORESTSEO_PROJECT_ID;

fetch('https://api.forestseo.com/v1/contents', {
  headers: {
    'Authorization': `API-Key ${apiKey}`,
    'X-Project-ID': projectId,
    'Content-Type': 'application/json',
  },
});

Key Rotation

Regularly rotate API keys to maintain security:

1. Create a new API key with the same purpose
2. Update your integrations with the new key
3. Test thoroughly to ensure all systems work
4. Disable the old key (don't delete yet)
5. Monitor for 24-48 hours for any failed requests
6. Delete the old key once confirmed unused

Access Control

• Use separate keys for different environments (dev, staging, production)
• Assign minimal permissions — create keys for users with least privilege needed
• Document key usage — maintain an inventory of where each key is used
• Audit regularly — review active keys and disable unused ones

🔄 Managing API Keys

Viewing API Keys

List all API keys in your account:

Key information displayed:

• Name and description
• Associated user
• Purpose category
• Creation date
• Last used timestamp
• Active/inactive status

Disabling API Keys

Temporarily revoke access without deleting the key:

1. Navigate to Settings → API Keys
2. Find the key in the list
3. Click the toggle switch or "Disable" button
4. Confirm the action

When disabled:

• ✅ Key information is preserved
• ✅ Can be re-enabled anytime
• ❌ All requests using this key will fail with 401 Unauthorized

Use cases:

• Investigating suspicious activity
• Temporarily pausing an integration
• Testing without permanent deletion

Deleting API Keys

Permanently remove an API key:

1. Navigate to Settings → API Keys
2. Find the key in the list
3. Click "Delete" (or trash icon)
4. Confirm deletion by typing the key name

🚨 Troubleshooting

Common Errors

401 Unauthorized

Causes:

• Missing Authorization header
• Incorrect API key format
• Invalid or disabled API key
• Expired or deleted key

Solution:

# ❌ Wrong format
Authorization: Bearer YOUR_API_KEY

# ❌ Wrong format
Authorization: YOUR_API_KEY

# ✅ Correct format
Authorization: API-Key YOUR_API_KEY

403 Forbidden

Causes:

• API key user lacks permissions for the requested resource
• Project access not granted to the key's user
• Operation not allowed for API key authentication

Solution:

• Verify the user associated with the API key has access to the project
• Check user role permissions
• Some sensitive operations may require interactive login

400 Bad Request (Missing Project Context)

Error message:

{
  "detail": "Project ID required. Include X-Project-ID header."
}

Solution:

# Add X-Project-ID header to your request
curl -X GET "https://api.forestseo.com/v1/contents" \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "X-Project-ID: proj_abc123"

Rate Limiting

API keys are subject to rate limits:

Rate limit headers in response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1640000000

When rate limited, you'll receive:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please try again in 60 seconds.",
  "retry_after": 60
}

💡 Integration Examples

Node.js

import axios from 'axios';

const client = axios.create({
  baseURL: 'https://api.forestseo.com/v1',
  headers: {
    'Authorization': `API-Key ${process.env.FORESTSEO_API_KEY}`,
    'X-Project-ID': process.env.FORESTSEO_PROJECT_ID,
    'Content-Type': 'application/json',
  },
});

// List contents
const response = await client.get('/contents');
console.log(response.data);

Python

import os
import requests

API_KEY = os.getenv('FORESTSEO_API_KEY')
PROJECT_ID = os.getenv('FORESTSEO_PROJECT_ID')

headers = {
    'Authorization': f'API-Key {API_KEY}',
    'X-Project-ID': PROJECT_ID,
    'Content-Type': 'application/json',
}

response = requests.get(
    'https://api.forestseo.com/v1/contents',
    headers=headers
)

print(response.json())

PHP

<?php

$apiKey = getenv('FORESTSEO_API_KEY');
$projectId = getenv('FORESTSEO_PROJECT_ID');

$ch = curl_init('https://api.forestseo.com/v1/contents');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: API-Key {$apiKey}",
        "X-Project-ID: {$projectId}",
        "Content-Type: application/json",
    ],
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

print_r($data);
curl_close($ch);

cURL (Bash Script)

#!/bin/bash

API_KEY="${FORESTSEO_API_KEY}"
PROJECT_ID="${FORESTSEO_PROJECT_ID}"

curl -X GET "https://api.forestseo.com/v1/contents" \
  -H "Authorization: API-Key ${API_KEY}" \
  -H "X-Project-ID: ${PROJECT_ID}" \
  -H "Content-Type: application/json"

📖 Next Steps

🆘 Need Help?