Hugo SaaS Backend

English

简体中文

English

简体中文

Appearance

Frontend Integration ​

This guide covers how to connect a frontend application to the local Hugo SaaS Backend services.

Prerequisites ​

Start all services locally:

bash
pnpm install
pnpm run db:reset
pnpm run dev:services

Environment Variables ​

Point your frontend to these local endpoints:

dotenv
VITE_ADMIN_BFF_GRAPHQL_URL=http://127.0.0.1:4010/graphql
VITE_ENTITLEMENT_GRAPHQL_URL=http://127.0.0.1:4317/graphql
VITE_ENTITLEMENT_REST_URL=http://127.0.0.1:4317
VITE_IDENTITY_REST_URL=http://127.0.0.1:4320
VITE_DEMO_ORGANIZATION_ID=org-demo-001
VariablePurpose
VITE_ADMIN_BFF_GRAPHQL_URLAdmin BFF GraphQL endpoint for organization, user, membership, role, and activity log queries
VITE_ENTITLEMENT_GRAPHQL_URLEntitlement Service GraphQL endpoint for product, entitlement, and allocation reads
VITE_ENTITLEMENT_REST_URLEntitlement Service REST endpoint for allocation updates and bulk import operations
VITE_IDENTITY_REST_URLIdentity Service endpoint for demo account switching

No authentication is required for local development. CORS is enabled for all local origins.

API Explorers ​

When services are running locally, the following interactive tools are available at these URLs:

ToolURL
Admin BFF GraphiQLhttp://127.0.0.1:4010/graphiql
Entitlement GraphiQLhttp://127.0.0.1:4317/graphiql
Entitlement Swagger UIhttp://127.0.0.1:4317/docs
Identity Swagger UIhttp://127.0.0.1:4320/docs

For static REST reference that works without running services, use the Redoc reference pages linked from the REST API sections.

Demo Account Switching ​

The Identity Service provides a simple account switching menu for local development. You can switch between different demo users to preview the UI under different roles and permissions. It does not perform real authentication — no real credentials or identity provider are involved.

  1. Fetch available demo accounts: GET /demo/accounts
  2. Select an account and get a session token: POST /demo/token with { "userId": "..." }
  3. Fetch the selected user's profile: GET /userinfo with Authorization: Bearer <token>

Example:

ts
const accountsRes = await fetch('http://127.0.0.1:4320/demo/accounts');
const accounts = await accountsRes.json();

const tokenRes = await fetch('http://127.0.0.1:4320/demo/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ userId: accounts.defaultAccountId }),
});
const { access_token } = await tokenRes.json();

const userInfoRes = await fetch('http://127.0.0.1:4320/userinfo', {
  headers: { Authorization: `Bearer ${access_token}` },
});
const userInfo = await userInfoRes.json();

The Admin BFF and Entitlement Service do not enforce this token for local requests — it exists purely so the frontend can display different account contexts (e.g., current user name, role) in the UI.

API Reference ​

MIT Licensed