Documentation

Everything you need to add API key auth to your API.

Quick Start

Harbor validates API keys and tracks usage. Pick your language and add one line to your server.

Node.js / Express

npm install harbor-sdk

const { harbor } = require('harbor-sdk');

// Add to your Express app — that's it
app.use(harbor({ projectId: 'proj_harbor_xyz' }));

// Access key info in any route
app.get('/data', (req, res) => {
  console.log(req.harbor.plan);          // 'pro'
  console.log(req.harbor.callsThisMonth); // 1042
  res.json({ data: 'protected!' });
});

Python

pip install harbor-sdk

# Flask
from harbor_sdk import harbor
from flask import g

@app.route("/data")
@harbor(project_id="proj_harbor_xyz")
def data():
    return {"plan": g.harbor.plan}

# FastAPI
from harbor_sdk import HarborMiddleware

app.add_middleware(HarborMiddleware, project_id="proj_harbor_xyz")

Go

go get github.com/nicolugo0503-glitch/harbor-go

import harbor "github.com/nicolugo0503-glitch/harbor-go"

mux.Handle("/data", harbor.Middleware(harbor.Config{
    ProjectID: "proj_harbor_xyz",
})(http.HandlerFunc(handler)))

func handler(w http.ResponseWriter, r *http.Request) {
    info := harbor.FromContext(r.Context())
    fmt.Fprintf(w, "Plan: %s", info.Plan)
}

Rust

# Cargo.toml
harbor-sdk = "0.1"

// Standalone validation
use harbor_sdk::validate;

match validate("hbr_live_your_key").await {
    Ok(info) => println!("Plan: {}", info.plan),
    Err(e) => println!("Error: {}", e),
}

// Axum middleware
use harbor_sdk::{HarborLayer, KeyInfo};
use axum::Extension;

let app = Router::new()
    .route("/data", get(handler))
    .layer(HarborLayer::new("proj_harbor_xyz"));

Local Development

Use harbor-mock to test locally without hitting production.

npx harbor-mock
# → Running at http://localhost:4747

# Built-in test keys:
#   hbr_test_free_key  → plan: free
#   hbr_test_pro_key   → plan: pro
#   hbr_test_scale_key → plan: scale

# Point your SDK at the mock:
const { harbor } = require('harbor-sdk');
app.use(harbor({
  projectId: 'proj_...',
  validateUrl: 'http://localhost:4747/api/validate'
}));

Validate Endpoint

Call GET /api/validate?key=YOUR_KEY directly from any language.

curl https://harbor-black.vercel.app/api/validate?key=hbr_live_xxx

{
  "valid": true,
  "keyId": "key_...",
  "projectId": "proj_...",
  "plan": "pro",
  "callsThisMonth": 1042,
  "name": "Production Key",
  "country": "US"
}

Rate limited to 120 requests/min per IP. Returns 429 with Retry-After: 60 when exceeded.

Customer Portal

Every project gets a shareable page where your customers can view their API keys.

https://harbor-black.vercel.app/portal/YOUR_PROJECT_ID

Share this URL with your API users. They'll see their keys, usage counts, and a quick-start code snippet.

Analytics

Every API call is automatically tracked. Open your dashboard and click the Analytics tab to see:

Call volume over the last 7 days
Success vs. invalid key rate
Today's call count
Real-time call log with IP, latency, and key ID

Plan-Based Access

Gate features by plan using the key info attached to every request.

// Node.js
app.get('/premium', (req, res) => {
  if (req.harbor.plan === 'free') {
    return res.status(403).json({ error: 'Upgrade to Pro to access this.' });
  }
  res.json({ data: 'premium content' });
});

# Python (Flask)
@app.route("/premium")
@harbor(project_id="proj_xyz")
def premium():
    if g.harbor.plan == "free":
        return {"error": "Upgrade required"}, 403
    return {"data": "premium content"}