# Vibe Coding Workflow — Authentication & Developer Integration Guide

This document defines how AI agents, LLMs, crawlers, and programmatic clients authenticate and interface with Vibe Coding Workflow APIs.

## 1. Zero-Friction Agent Onboarding

Vibe Coding Workflow is an entirely client-side, local-first web application and developer specification generator.

- **No Sign-Up Wall:** No user registration, email verification, credit card, or "contact sales" forms are required.
- **Instant Programmatic Access:** Autonomous agents and developers can probe, query, and generate specifications immediately.
- **Local Secrets (BYOK):** All AI provider API keys (Gemini, OpenAI, Anthropic, xAI, DeepSeek, Groq, Mistral, OpenRouter) are supplied directly by the client and stored in browser `localStorage`.
- **No Server Persistence:** Keys are never stored or logged on our servers.

## 2. API Authentication & Headers

For programmatic access to serverless generation routes (`/api/v1/generate`, `/api/v1/deep-research`, `/api/v1/agent-workflow`):

- **Header Authentication:** Pass your provider key in the `x-provider-key` header or `Authorization: Bearer <API_KEY>` header.
- **Payload Authentication:** Pass the key in the JSON request body field `apiKey`.
- **Content-Type:** `application/json; charset=utf-8`

## 3. API Versioning & Deprecation Policy

- **Path Versioning:** `/api/v1/*` (with `/api/*` aliased to `/api/v1/*`).
- **Header Versioning:** `X-API-Version: 1.0.0`
- **Deprecation Policy:** Deprecated endpoints are supported for a minimum of 180 days after deprecation notice. Notices are signaled using RFC 8594 `Deprecation` and `Sunset` HTTP response headers.

## 4. Rate Limiting Policy

Standard RFC rate limiting headers are returned on all API responses:
- `RateLimit-Limit: 60` (allowed requests per minute)
- `RateLimit-Remaining: 59` (remaining requests in window)
- `RateLimit-Reset: 60` (seconds until quota resets)
- `Retry-After: 60` (returned on HTTP 429 status)

## 5. Structured Error Model (RFC 9457)

All 4xx and 5xx responses return typed JSON errors:
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing provider API key",
    "resolutionHint": "Supply a valid API key in the x-provider-key header or apiKey body property.",
    "details": null
  },
  "status": 400,
  "requestId": "gen_8f7b3c2a",
  "timestamp": "2026-08-22T12:00:00.000Z"
}
```

## 6. Developer & Agent Resources

- **Developer Portal:** https://vibeworkflow.com/developers
- **OpenAPI 3.0.3 Spec:** https://vibeworkflow.com/openapi.json
- **Agent Instructions:** https://vibeworkflow.com/agent-instructions.md
- **Claude Code Skills:** https://vibeworkflow.com/.well-known/agent-skills/index.json
- **MCP Server Card:** https://vibeworkflow.com/.well-known/mcp/server-card.json
- **Markdown Content Negotiation:** Send `Accept: text/markdown` to any URL on https://vibeworkflow.com