Applications Module - Class Diagram

The Applications module manages OAuth-style API client applications and their API keys. Each Application represents a programmatic consumer of the API (a CLI, a server-side integration, a mobile build identifier) and ships with a single API key whose plaintext value is shown only once at creation/rotation. The auth middleware validates X-API-Key headers against this module’s hashed-key index on every request that doesn’t carry a JWT.

Class Diagram

Request Flow

1. HTTP Request → Controller receives application CRUD or key-rotation request.
2. Auth Check → Middleware verifies JWT; Controller extracts the calling user.
3. Permission Check → Service confirms the caller owns (or can manage) the application.
4. Key Generation → For create/rotate, Service generates a new API key, hashes it, and stores only the hash.
5. Persistence → Repository writes the application record.
6. Response → Service returns the model; the plaintext key is returned exactly once at create/rotate time.

Key Components

Controller

HTTP edge: parses request bodies, enforces shape, returns appropriate 201/200/204 codes.

Service

• Generates and hashes API keys (only the hash hits the database).
• ValidateAPIKey is called by the auth middleware on every request that presents an X-API-Key header.
• ValidateAPIKeyForAuth returns (userID, scopes) for use by downstream permission checks.

Repository

Stores applications rows keyed by ID, with a unique index on the API-key hash for fast validation lookups.

SDK Surface

• ApplicationsService — create, getById, list, update, delete, rotateKey.
• Application — canonical wire shape.
• actions/application — undo/redo-aware actions for the applications admin panel.

Cross-Module Integration

• Auth middleware (pkg/middleware) calls ValidateAPIKey(key) on every request without a JWT. The match is against the hash, not the plaintext.
• Permissions — API keys inherit the calling user’s system role and per-blob permissions; there’s no separate scope system today.
• Users — every Application is owned by exactly one User; deletes cascade.

API Reference

See the interactive API reference /applications tag for live examples.