Shell API

Base URL: http://localhost:3000 Base path: /api

Authentication: Authorization: Bearer <shell-jwt> unless marked Public.

Response envelope:

{ "data": {}, "message": "ok" }

Error envelope:

{ "error": { "code": "UNAUTHORIZED", "message": "..." } }

Status	Meaning
400	Bad request / validation error
401	Missing or invalid JWT
403	Insufficient permissions
404	Not found
409	Conflict (already exists)
500	Server error

---

Auth GET POST PUT

Base path: /api/auth

Method	Path	Auth	Description
GET	/providers	Public	List enabled OAuth providers
GET	/login	Public	Start PKCE flow — returns Keycloak authorization URL
GET	/callback	Public	Handle OAuth callback — issues Shell JWT
POST	/local-login	Public	Username + password login
POST	/register	Public	Register new user with plan selection
POST	/refresh	Required	Refresh Shell JWT
POST	/exchange	Required	Exchange Shell JWT for service JWT (gRPC gateway)
POST	/exchange-keycloak	Optional	Exchange Keycloak token for service JWT
POST	/change-password	Required	Change password
POST	/request-password-reset	Public	Request password reset
POST	/confirm-password-reset	Public	Confirm password reset with token
GET	/me	Required	Current user profile + organization
PUT	/me/preferences	Required	Update user preferences

POST /api/auth/local-login

// Request
{ "username": "veni", "password": "veni" }

// Response
{ "data": { "accessToken": "<shell-jwt>", "tokenType": "Bearer", "expiresIn": 3600 } }

GET /api/auth/callback

Query params: code, state

// Response
{ "data": { "accessToken": "<shell-jwt>", "user": { "id": "...", "email": "..." } } }

POST /api/auth/exchange-keycloak

// Request
{ "token": "<keycloak-access-token>" }

// Response
{ "data": { "accessToken": "<service-jwt>", "tokenType": "Bearer", "expiresIn": 3600 } }

---

Users GET POST PUT DELETE

Base path: /api/users — requires JWT. Most endpoints require users:* permissions.

Method	Path	Permission	Description
GET	/	users:list	List users (paginated, filterable)
POST	/	users:write	Create user
GET	/:id	users:read	Get user with roles
PUT	/:id	users:write	Update user
DELETE	/:id	users:delete	Delete user
GET	/:id/roles	users:read	List user's roles
POST	/:id/roles	users:write	Assign roles to user
DELETE	/:id/roles/:roleId	users:write	Remove role from user

---

Roles GET POST PUT DELETE

Base path: /api/roles

Method	Path	Permission	Description
GET	/	roles:list	List roles (paginated)
POST	/	roles:write	Create role
GET	/:id	roles:read	Get role with permissions
PUT	/:id	roles:write	Update role
DELETE	/:id	roles:delete	Delete role
GET	/:id/permissions	roles:read	List role's permissions
POST	/:id/permissions	roles:write	Update role's permissions

---

Permissions GET

Method	Path	Permission	Description
GET	/api/permissions	permissions:list	List all permissions

---

Organizations GET PUT

Method	Path	Permission	Description
GET	/api/organizations	organizations:list	List organizations
GET	/api/organizations/:id	organizations:read	Get org with users
PUT	/api/organizations/:id	organizations:write	Update org
PUT	/api/organizations/:id/subscription	subscriptions:admin	Admin override subscription

---

Subscriptions GET POST PUT DELETE

Base path: /api/subscriptions

Method	Path	Auth	Description
POST	/upgrade	Required	Create Stripe Checkout session
POST	/upgrade-direct	Required	Upgrade with saved payment method
POST	/webhook	Public (Stripe sig)	Stripe webhook handler
GET	/portal	Required	Get Stripe billing portal URL
GET	/current	Required	Get current subscription
GET	/usage	Required	Get usage summary
POST	/check-limit	Required	Check if within plan limit
POST	/consume	Required	Record usage consumption
POST	/payment-methods/setup	Required	Create Stripe SetupIntent
GET	/payment-methods	Required	List saved payment methods
DELETE	/payment-methods/:id	Required	Delete payment method
PUT	/payment-methods/:id/default	Required	Set default payment method

---

Plans GET POST PUT

Base path: /api/plans

Method	Path	Auth	Description
GET	/	Public	List active subscription plans
GET	/:id	Public	Get plan with included services
POST	/	plans:write	Create plan
PUT	/:id	plans:write	Update plan
GET	/:id/limits	plans:read	Get plan limits
PUT	/:id/limits	plans:write	Set plan limits
POST	/:id/sync-stripe	plans:write	Sync plan to Stripe

---

Services (Admin) GET POST PUT DELETE

Base path: /api/admin/apps

Method	Path	Permission	Description
GET	/	apps:list	List services
GET	/:id	apps:read	Get service
POST	/	apps:write	Register service
POST	/register-remote	apps:write	Auto-register by entry URL
PUT	/:id	apps:write	Update service
DELETE	/:id	apps:delete	Delete service

---

Config GET

Method	Path	Auth	Description
GET	/api/config	Required	Admin config (Keycloak, services, features)
GET	/api/config/apps	Public	Active service list (used by Shell UI on load)
GET	/api/config/plans	Public	Active subscription plans

---

Dashboard & Audit GET

Method	Path	Permission	Description
GET	/api/admin/stats	settings:read	Dashboard statistics
GET	/api/admin/audit	settings:read	Activity logs (paginated)

---

Onboarding GET POST PUT

Base path: /api/onboarding

Method	Path	Auth	Description
POST	/	Public	Submit onboarding request
GET	/	onboarding:list	List requests
GET	/:id	onboarding:read	Get request detail
PUT	/:id/approve	onboarding:approve	Approve request
PUT	/:id/reject	onboarding:reject	Reject with reason