# 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

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
- All `/api/v1/images` endpoints
- All `/api/v1/flows` endpoints
- `/api/v1/live` generation endpoint

**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)

---

## Error Codes

| Code | Description |
|------|-------------|
| 401 | Unauthorized - Missing, invalid, expired, or revoked API key |
| 403 | Forbidden - Insufficient permissions (master key required) |
| 429 | Too Many Requests - Rate limit exceeded |

**Common Error Messages:**
- `"Missing API key"` - No X-API-Key header provided
- `"Invalid API key"` - Key is invalid, expired, or revoked
- `"Master key required"` - Endpoint requires master key, project key insufficient
- `"Bootstrap not allowed"` - Keys already exist, cannot bootstrap again
- `"Rate limit exceeded"` - Too many requests, retry after specified time