API Keys

API keys are the primary authentication method for programmatic access to the Boring API. This guide explains how to generate, manage, and use API keys securely.

What are API Keys?

API keys are unique identifiers that authenticate your API requests. Each key:

• Starts with the prefix boring_
• Is tied to your Google account (email)
• Can be named for easy identification
• Tracks last usage timestamp
• Can be deactivated or deleted anytime

Generating API Keys

Step-by-Step Guide

1. Sign in to Boring Dashboard
2. Click on Settings in the navigation menu
3. In the API Keys section, click "Generate New API Key"
4. Enter a descriptive name for the key:
   • Good examples: "Production Server", "Development", "Mobile App", "QA Testing"
   • Bad examples: "Key1", "Test", "My Key"
5. Click "Generate"
6. Copy the API key immediately - you won't be able to view it again!
7. Store the key securely (environment variable, secrets manager, etc.)

API Key Format

boring_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

• Prefix: boring_
• Length: 43 characters total
• Content: Alphanumeric string

Managing API Keys

View Your API Keys

Navigate to the Settings page to see all your API keys:

Note: Only the first few characters of each key are displayed for security.

Track Usage

Each API key shows:

• Created: When the key was generated
• Last Used: When the key was last used in an API request (or "Never")

This helps you identify:

• Inactive keys that can be deleted
• Suspicious activity if a key shows recent usage you don't recognize

Delete API Keys

To delete an API key:

1. Go to Settings page
2. Find the key you want to delete
3. Click the "Delete" button
4. Confirm the deletion

Important: Deleted keys are immediately deactivated. Any services using that key will receive authentication errors.

Using API Keys

Request Header

Include your API key in the boring-api-key header of every API request:

POST /v2/posts HTTP/1.1
Host: boring.aiagent-me.com
Content-Type: application/json
boring-api-key: boring_xxxxxxxxxxxxx

{
  "post": {...}
}

Code Examples

Python (requests)

import requests
import os

API_KEY = os.environ.get("BORING_API_KEY")
API_URL = "https://boring.aiagent-me.com/v2/posts"

headers = {
    "boring-api-key": API_KEY,
    "Content-Type": "application/json"
}

response = requests.post(API_URL, headers=headers, json=post_data)

JavaScript (Node.js)

const API_KEY = process.env.BORING_API_KEY;
const API_URL = "https://boring.aiagent-me.com/v2/posts";

const response = await fetch(API_URL, {
  method: "POST",
  headers: {
    "boring-api-key": API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(postData)
});

Python (http.client)

import http.client
import json
import os

conn = http.client.HTTPSConnection("boring.aiagent-me.com")

headers = {
    "boring-api-key": os.environ["BORING_API_KEY"],
    "Content-Type": "application/json"
}

conn.request("POST", "/v2/posts", json.dumps(post_data), headers)
response = conn.getresponse()

cURL

export BORING_API_KEY="boring_xxxxxxxxxxxxx"

curl -X POST https://boring.aiagent-me.com/v2/posts \
  -H "boring-api-key: $BORING_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Security Best Practices

1. Use Environment Variables

Never hardcode API keys in your source code!

Good:

import os
API_KEY = os.environ.get("BORING_API_KEY")

Bad:

API_KEY = "boring_abc123..."  # DON'T DO THIS!

2. Add to .gitignore

If you use .env files, always exclude them from version control:

# .gitignore
.env
.env.local
*.env

3. Rotate Keys Regularly

Best practices:

• Rotate production keys every 3-6 months
• Generate new keys after team member departures
• Create separate keys for each service/environment

4. Use Different Keys for Different Environments

# Development
BORING_API_KEY=boring_dev_xxxxxxxxxxxxx

# Staging
BORING_API_KEY=boring_staging_xxxxxxxxxxxxx

# Production
BORING_API_KEY=boring_prod_xxxxxxxxxxxxx

Name them accordingly in the Settings page for easy identification.

5. Monitor API Key Usage

Regularly check the Last Used column in Settings:

• Identify unused keys and delete them
• Detect suspicious activity
• Audit which services are using which keys

6. Immediate Response to Compromises

If an API key is compromised:

1. Delete it immediately from the Settings page
2. Generate a new key with a different name
3. Update your applications with the new key
4. Investigate how the compromise occurred

Troubleshooting

Authentication Error

If you receive an authentication error:

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

Check:

1. Header name is exactly boring-api-key (case-sensitive)
2. Key starts with boring_ prefix
3. Key hasn't been deleted from Settings
4. No extra spaces or newlines in the key value

Key Not Working

If a valid-looking key doesn't work:

1. Verify the key in Settings page (check first few characters)
2. Ensure you copied the entire key
3. Check for hidden characters (copy directly from terminal/editor)
4. Generate a new key and test with that

Last Used Not Updating

The "Last Used" timestamp updates when:

• The API key is successfully validated
• An API request is processed

It may take a few minutes to reflect in the UI.

API Endpoints

List API Keys

GET /api/keys HTTP/1.1
Host: boring.aiagent-me.com
Cookie: session=...

Response:

{
  "keys": [
    {
      "id": "uuid",
      "name": "Production",
      "key_preview": "boring_abc...",
      "created_at": "2025-01-15T10:30:00Z",
      "last_used_at": "2025-01-20T15:45:00Z",
      "is_active": true
    }
  ]
}

Note: This endpoint requires dashboard authentication (session cookie), not an API key.

Delete API Key

DELETE /api/keys/{key_id} HTTP/1.1
Host: boring.aiagent-me.com
Cookie: session=...

Note: This endpoint requires dashboard authentication (session cookie), not an API key.

Multiple API Keys

You can generate multiple API keys for different purposes:

Benefits:

• Isolation: Compromise of one key doesn't affect others
• Tracking: Know which service made which requests
• Revocation: Disable specific integrations without affecting others

Next Steps

Now that you have your API key, you're ready to start publishing:

• Publishing API - Learn the publishing endpoint
• Examples - See complete code examples
• Platforms - Platform-specific guides