usulpro
/
banatie-service
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
banatie-service/docs/api/admin.md

4.3 KiB
Raw Blame History

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