# Banatie API - Administration & Authentication

## Authentication Overview

All API endpoints (except public endpoints and bootstrap) require authentication via API key in the `X-API-Key` header.

### API Key Types

**Master Keys**
- Full administrative access
- Never expire
- Can create and revoke other API keys
- Access to all admin endpoints

**Project Keys**
- Standard access for image generation
- Expire in 90 days by default
- Scoped to specific organization and project
- Rate limited (100 requests/hour)

### Header Format

```
X-API-Key: bnt_your_key_here
```

---

## Public Endpoints

### GET /health

Health check with server status.

**Authentication:** None

**Purpose:** Monitor API availability and uptime

**Returns:** Status, timestamp, uptime, environment, version

---

### GET /api/info

API information and configuration limits.

**Authentication:** Optional (returns key info if authenticated)

**Purpose:** Discover API capabilities and limits

**Returns:** API name, version, endpoints list, file size/format limits

---

## Bootstrap Endpoint

### POST /api/bootstrap/initial-key

Create the first master API key (one-time only).

**Authentication:** None (public, works only when database is empty)

**Purpose:** Initialize the API with first master key

**Notes:**
- Only works when no API keys exist in database
- Returns master key value (save securely, shown only once)
- Subsequent calls return 403 Forbidden

---

## API Key Management

All endpoints require Master Key authentication.

### POST /api/admin/keys

Create new API key (master or project).

**Authentication:** Master Key required

**Parameters:**
- `type` - "master" or "project" (required)
- `projectId` - Project identifier (required for project keys)
- `organizationId` - Organization UUID (optional, auto-created)
- `organizationSlug` - Organization slug (optional, auto-created)
- `projectSlug` - Project slug (optional, auto-created)
- `name` - Friendly name for the key (optional)
- `expiresInDays` - Expiration days (optional, default: 90 for project keys)

**Purpose:** Generate new API keys for projects or admin users

**Notes:**
- Automatically creates organization and project if they don't exist
- Returns API key value (save securely, shown only once)
- Master keys never expire, project keys expire in 90 days by default

---

### GET /api/admin/keys

List all API keys.

**Authentication:** Master Key required

**Purpose:** View all active and inactive API keys

**Returns:** Array of all keys with metadata (no sensitive key values), includes organization and project details

**Notes:**
- Shows all keys regardless of active status
- Includes last used timestamp
- Does not return actual API key values (hashed in database)

---

### DELETE /api/admin/keys/:keyId

Revoke an API key.

**Authentication:** Master Key required

**Parameters:**
- `keyId` - UUID of the key to revoke (path parameter)

**Purpose:** Deactivate an API key (soft delete)

**Notes:**
- Soft delete via `is_active` flag
- Revoked keys cannot be reactivated
- Key remains in database for audit trail

---

## Rate Limiting

### API Key Rate Limiting

Rate limits apply per API key to protected endpoints.

**Limits:**
- **Project Keys:** 100 requests per hour
- **Master Keys:** No rate limit on admin endpoints

**Affected Endpoints:**
- All `/api/v1/generations` endpoints (POST, PUT, regenerate)
- All `/api/v1/images` endpoints (POST upload, PUT)
- All `/api/v1/flows` endpoints (PUT, regenerate)
- All `/api/v1/live/scopes` endpoints (POST, PUT, regenerate, DELETE)

**Response Headers:**
- `X-RateLimit-Limit` - Maximum requests per window
- `X-RateLimit-Remaining` - Requests remaining
- `X-RateLimit-Reset` - Reset timestamp (ISO 8601)

**429 Too Many Requests:**
- Returned when limit exceeded
- Includes `Retry-After` header (seconds until reset)

---

### IP-Based Rate Limiting (Live URLs)

Separate rate limiting for public live URL generation endpoints.

**Limits:**
- **10 new generations per hour per IP address**
- Only cache MISS (new generations) count toward limit
- Cache HIT (cached images) do NOT count toward limit

**Affected Endpoints:**
- `GET /:orgSlug/:projectSlug/live/:scope` - Public live URL generation

**Purpose:**
- Prevent abuse of public live URL endpoints
- Separate from API key limits (for authenticated endpoints)
- Does not affect API key-authenticated endpoints

**Response Headers:**
- `X-RateLimit-Limit` - Maximum requests per window (10)
- `X-RateLimit-Remaining` - Requests remaining
- `X-RateLimit-Reset` - Seconds until reset

**429 Too Many Requests:**
- Returned when IP limit exceeded
- Includes `Retry-After` header (seconds until reset)
- Error code: `IP_RATE_LIMIT_EXCEEDED`

**Notes:**
- Uses in-memory store with automatic cleanup
- Supports X-Forwarded-For header for proxy/load balancer setups
- IP limit resets every hour per IP address

---

## Error Codes

### HTTP Status Codes

| Code | Description |
|------|-------------|
| 401 | Unauthorized - Missing, invalid, expired, or revoked API key |
| 403 | Forbidden - Insufficient permissions (master key required) |
| 409 | Conflict - Resource already exists (e.g., duplicate scope slug) |
| 429 | Too Many Requests - Rate limit exceeded (API key or IP) |

### Authentication Error Codes

| Error Code | HTTP Status | Description |
|------------|-------------|-------------|
| `MISSING_API_KEY` | 401 | No X-API-Key header provided |
| `INVALID_API_KEY` | 401 | Key is invalid, expired, or revoked |
| `MASTER_KEY_REQUIRED` | 403 | Endpoint requires master key, project key insufficient |
| `BOOTSTRAP_NOT_ALLOWED` | 403 | Keys already exist, cannot bootstrap again |

### Rate Limiting Error Codes

| Error Code | HTTP Status | Description |
|------------|-------------|-------------|
| `RATE_LIMIT_EXCEEDED` | 429 | API key rate limit exceeded (100/hour) |
| `IP_RATE_LIMIT_EXCEEDED` | 429 | IP rate limit exceeded for live URLs (10/hour) |

### Live Scope Error Codes

| Error Code | HTTP Status | Description |
|------------|-------------|-------------|
| `SCOPE_INVALID_FORMAT` | 400 | Scope slug format invalid (must be alphanumeric + hyphens + underscores) |
| `SCOPE_ALREADY_EXISTS` | 409 | Scope with this slug already exists in project |
| `SCOPE_NOT_FOUND` | 404 | Scope does not exist or access denied |
| `IMAGE_NOT_IN_SCOPE` | 400 | Image does not belong to specified scope |

**Notes:**
- All error responses follow the format: `{ "success": false, "error": { "message": "...", "code": "..." } }`
- Rate limit errors include `Retry-After` header with seconds until reset
- Scope management endpoints require project key authentication