Authentication

Overview

SkillBoss uses API key authentication via Bearer tokens in HTTP headers. Every request must include your unique API key.

Getting Your API Key

Quick setup for AI agents: Tell your agent set up skillboss.co/skill.md to auto-configure everything.

# Your SkillBoss API Key
SKILLBOSS_KEY=sk-abc123def456...

Using Your API Key

HTTP Header

Include your key in the Authorization header:

Authorization: Bearer YOUR_SKILLBOSS_KEY

Example Request

curl https://api.skillboss.co/v1/chat/completions \
  -H "Authorization: Bearer sk-abc123..." \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-4-5-sonnet", "messages": [{"role": "user", "content": "Hello"}]}'

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.skillboss.co/v1",
    api_key=os.environ["SKILLBOSS_KEY"]
)

response = client.chat.completions.create(
    model="claude-4-5-sonnet",
    messages=[{"role": "user", "content": "Hello"}]
)

import OpenAI from 'openai'

const client = new OpenAI({
  baseURL: 'https://api.skillboss.co/v1',
  apiKey: process.env.SKILLBOSS_KEY
})

const response = await client.chat.completions.create({
  model: 'claude-4-5-sonnet',
  messages: [{role: 'user', content: 'Hello'}]
})

Security Best Practices

✅ DO: Use Environment Variables

Store keys in environment variables, not in code:

# .env (add to .gitignore!)
SKILLBOSS_KEY=sk-abc123...

import os
api_key = os.environ["SKILLBOSS_KEY"]  # ✅ Good

const apiKey = process.env.SKILLBOSS_KEY  // ✅ Good

❌ DON'T: Hardcode Keys

api_key = "sk-abc123..."  # ❌ Bad! Never hardcode

const apiKey = 'sk-abc123...'  // ❌ Bad! Will leak in Git

Server-Side Only

// app/api/chat/route.ts (server-side)
import { OpenAI } from 'openai'

export async function POST(req: Request) {
  const client = new OpenAI({
    baseURL: 'https://api.skillboss.co/v1',
    apiKey: process.env.SKILLBOSS_KEY  // ✅ Safe: server-side
  })

  const response = await client.chat.completions.create({...})
  return Response.json(response)
}

// components/Chat.tsx (runs in browser)
'use client'

export function Chat() {
  const apiKey = process.env.NEXT_PUBLIC_SKILLBOSS_KEY  // ❌ EXPOSED!

  // This code runs in the browser - API key will be visible
  // in Network tab of DevTools
}

Key Management

Rotating Keys

Rate Limiting

API keys are subject to rate limits based on your plan:

Rate Limit Headers

Responses include rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000

Handling Rate Limits

import time
from openai import RateLimitError

try:
    response = client.chat.completions.create(...)
except RateLimitError as e:
    retry_after = int(e.response.headers.get("Retry-After", 60))
    print(f"Rate limited. Retrying after {retry_after}s")
    time.sleep(retry_after)
    response = client.chat.completions.create(...)

Monitoring Usage

Track your API usage and credit balance in the console:

Balance Warnings

When your balance drops below 10 credits, API responses include a warning:

{
  "choices": [...],
  "_balance_warning": true,
  "_remaining_credits": 7.23
}

Handle this in your application:

const response = await client.chat.completions.create(...)

if (response._balance_warning) {
  console.warn(`Low balance: ${response._remaining_credits} credits remaining`)
  // Send notification, trigger auto-recharge, etc.
}

Troubleshooting

"Unauthorized" Error

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Causes:

• Missing Authorization header
• Incorrect key format
• Expired or revoked key

Solution:

• Verify header format: Authorization: Bearer sk-...
• Re-download Skills Pack from console
• Check for typos or truncated keys

"Insufficient Credits" Error

{
  "error": {
    "message": "Insufficient credits",
    "type": "insufficient_balance",
    "code": "insufficient_balance"
  }
}

Solution:

• Add credits to your account
• Enable auto-recharge to prevent interruptions

Next Steps