Authentication

Learn how to authenticate your requests to the Halfred API using API keys, manage them securely, and follow security best practices.

Overview

All requests to the Halfred API require authentication using an API key. API keys are associated with your account and allow you to track usage, and see recent logs status.

Getting an API Key

First Time Login

When you log in to your Halfred dashboard for the first time:

1. Halfred automatically creates a default project for you

2. Your API key is automatically generated and displayed

3. Copy and store your API key securely - you'll need it for your integration

⚠️ Important: Store your API key safely. While you can regenerate it later, any applications using the old key will stop working.

Regenerating Your API Key

If you lose your API key or need to revoke it for security reasons:

1. Go to your Halfred dashboard

2. Navigate to the "Your Key" section

3. Click the three dots menu (⋮)

4. Select "Revoke Key & Get New One"

5. Copy your new API key immediately

⚠️ Warning: Revoking your key is immediate. Update all applications using the old key to avoid service interruption.

API Key Format

Halfred API keys follow this format:

halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

All keys start with the halfred_ prefix followed by a unique identifier.

Using API Keys

HTTP Header Authentication

Include your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Examples

cURL

curl -X POST "https://api.halfred.ai/v1/chat/completions" \
  -H "Authorization: Bearer halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "standard",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Node.js (Halfred SDK)

import { Halfred } from "halfred.ai";

const client = new Halfred({
  apiKey: "halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
});

Python (Halfred SDK)

from halfred import Halfred

client = Halfred(api_key="halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx")

JavaScript (fetch)

const response = await fetch("https://api.halfred.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "standard",
    messages: [{ role: "user", content: "Hello!" }],
  }),
});

Environment Variables

Store your API keys in environment variables instead of hardcoding them.

Node.js

# .env file
HALFRED_API_KEY=halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

import { Halfred } from "halfred.ai";

const client = new Halfred();

The SDK automatically reads the HALFRED_API_KEY environment variable. You can also explicitly provide the API key:

const client = new Halfred({
  apiKey: process.env.HALFRED_API_KEY,
});

Python

# .env file or shell
export HALFRED_API_KEY="halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

import os
from halfred import Halfred

client = Halfred(api_key=os.environ.get("HALFRED_API_KEY"))

Security Best Practices

✅ DO

• Store keys securely: Use environment variables or secret management services

• Rotate keys regularly: Generate new keys periodically and revoke old ones

• Monitor usage: Check your dashboard for unusual activity

• Use server-side only: Never expose API keys in client-side code or mobile apps

❌ DON'T

• Don't commit to version control: Never add API keys to Git repositories

• Don't hardcode keys: Avoid putting keys directly in source code

• Don't expose in browsers: Never include keys in frontend JavaScript

• Don't log keys: Avoid logging API keys in application logs

Managing API Keys

Viewing Your Keys

In your project dashboard:

1. Go to Dashboard

2. Navigate to the Your Key section

3. View the active key

Note: For security, only few characters of key are displayed.

Revoking Keys

If a key is compromised or no longer needed:

1. Navigate to the "Your Key" section

2. Click the three dots menu (⋮)

3. Select "Revoke Key & Get New One"

4. Copy your new API key immediately

⚠️ Warning: Revoking a key is immediate and irreversible. Any applications using that key will stop working.

Troubleshooting

Authentication Failed (401)

Error Message: "Invalid API key" or "Authentication failed"

Solutions:

• Verify you've included the full API key with the halfred_ prefix

• Check that the key hasn't been revoked

• Ensure you're using the correct Authorization: Bearer header format

• Confirm the key belongs to the correct project

Key Not Found

Error Message: "API key not found"

Solution: The key may have been revoked. Generate a new key in your dashboard.

Testing Authentication

Test your API key with a simple request:

curl -X GET "https://api.halfred.ai/v1/models" \
  -H "Authorization: Bearer halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

If successful, you'll receive a list of available models. If authentication fails, you'll see an error message.

Support

For authentication issues:

• Dashboard: Check your project's API Keys section

• Email: [email protected]

• Discord: Join our community

---

Next Steps: Now that you understand authentication, explore our SDK Integration guides or REST API Reference.