API Specification

The Shell API provides a unified interface for identity management, service discovery, and platform orchestration. It exposes both REST (OpenAPI) and gRPC (Connect RPC) endpoints.

1. REST API (Public & Admin)

The REST API follows standard HTTP status codes and returns a consistent JSON envelope: { code, data, messageError? }.

Authentication & Identity

Endpoint	Method	Description
/auth/login	GET	Get OIDC authorization URL.
/auth/callback	GET	Handle OIDC callback and issue Shell JWT.
/auth/refresh	POST	Refresh Shell JWT using Refresh Token.
/auth/logout	POST	Blacklist current token and terminate session.
/auth/me	GET	Get current user profile and organization.

App Registry (Discovery)

Endpoint	Method	Description
/config/apps	GET	Public: List all available satellite apps.
/admin/apps	GET	Admin: List all apps with detailed metadata.
/admin/apps	POST	Admin: Register a new satellite app.

---

2. gRPC / Connect RPC

For service-to-service communication, the Shell provides a high-performance gRPC gateway using the Connect RPC protocol (JSON over HTTP/2).

AuthGateway

Used by satellite apps to exchange tokens or verify identity.

• Package: auth.v1
• Method: ExchangeForService(ExchangeForServiceRequest) returns (ExchangeForServiceResponse)

RbacService

Used by satellites to perform granular permission checks against the central Casbin engine.

• Package: rbac.v1
• Method: CheckPermission(CheckPermissionRequest) returns (CheckPermissionResponse)
• Method: GetUserPermissions(GetUserPermissionsRequest) returns (GetUserPermissionsResponse)

---

3. Documentation & Discovery

Interactive Explorer

The Shell API automatically generates OpenAPI 3.0 documentation.

• JSON Spec: GET /api/doc/openapi.json
• Swagger UI: GET /api/doc/explorer

Health Check

Monitors database connectivity and Redis availability.

• Endpoint: GET /api/health
• Response: { status: "UP", version: "1.0.0" }