174 lines
4.3 KiB
Markdown
174 lines
4.3 KiB
Markdown
# 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
|