# Customize the Developer Portal The [API7 Developer Portal Boilerplate](https://github.com/api7/api7-portal-boilerplate) is a customizable TanStack Start application built with React, Tailwind CSS, Better Auth, and the API7 Portal SDK. This guide covers the most common source-level customizations. This page refers to the Boilerplate because it is the public reference implementation for custom portal development. API7 Enterprise deployment docs may also refer to the official frontend image used in product deployments. ## Branding[​](#branding "Direct link to Branding") ### Logo and Site Icon[​](#logo-and-site-icon "Direct link to Logo and Site Icon") Replace the following files with your organization's assets: | Asset | File Path | Purpose | | --------- | ------------------------------ | -------------------------------------------- | | Site icon | `apps/site/public/favicon.ico` | Browser tab icon and the default header logo | ### Application Name and Description[​](#application-name-and-description "Direct link to Application Name and Description") Update the `config.yaml` to change the portal name and description: config.yaml ``` app: name: "Acme API Portal" desc: "Discover and integrate with Acme APIs" ``` The `name` appears in the browser title bar and the portal header. The `desc` is used for SEO meta descriptions. ### Theme[​](#theme "Direct link to Theme") The portal uses Tailwind CSS and the shared `@api7/portal-ui` styles. Edit `apps/site/src/globals.css` to add portal-specific theme variables or overrides: apps/site/src/globals.css ``` :root { --primary: oklch(0.55 0.18 255); --primary-foreground: oklch(0.985 0 0); --background: oklch(1 0 0); --foreground: oklch(0.145 0 0); } ``` The shared component theme is imported from `@api7/portal-ui/styles.css`. Inspect that package before overriding its custom properties so the light and dark themes remain consistent. note Branding changes (logo, site icon, CSS) require rebuilding and redeploying the application. Configuration changes in `config.yaml` require restarting the application. ## Authentication Customization[​](#authentication-customization "Direct link to Authentication Customization") ### Email and Password[​](#email-and-password "Direct link to Email and Password") Control email-and-password authentication in `config.yaml`: config.yaml ``` auth: emailAndPassword: enabled: true requireEmailVerification: false ``` To enable email verification, add a verification-email sender to the Better Auth configuration in `apps/site/src/lib/auth/server.ts`. Do not set `requireEmailVerification: true` until that sender is implemented, because users otherwise cannot complete email-and-password sign-up. ### Social Login Providers[​](#social-login-providers "Direct link to Social Login Providers") Add OAuth-based social login providers in `config.yaml`: config.yaml ``` auth: socialProviders: github: clientId: ${GITHUB_CLIENT_ID} clientSecret: ${GITHUB_CLIENT_SECRET} google: clientId: ${GOOGLE_CLIENT_ID} clientSecret: ${GOOGLE_CLIENT_SECRET} ``` Register an OAuth application with each provider to obtain the client ID and secret. Set the callback URL to `https:///api/auth/callback/`. ### Generic OpenID Connect Providers[​](#generic-openid-connect-providers "Direct link to Generic OpenID Connect Providers") For an OpenID Connect provider that is not included in the built-in social providers, add it to `auth.genericOAuthProviders`: config.yaml ``` auth: genericOAuthProviders: - providerId: keycloak discoveryUrl: https://id.example.com/realms/acme/.well-known/openid-configuration clientId: ${OIDC_CLIENT_ID} clientSecret: ${OIDC_CLIENT_SECRET} scopes: - openid - profile - email ``` The released Boilerplate registers these entries with the generic OAuth plugin from Better Auth. Use the callback URL shown by your provider configuration when registering the client with the identity provider. ## Extending Functionality[​](#extending-functionality "Direct link to Extending Functionality") The Boilerplate provides several extension points: | Extension Point | Location | Description | | --------------- | --------------------------- | -------------------------------------------------------------------- | | Routes | `apps/site/src/routes/` | Add pages and server routes with TanStack Router file-based routing. | | Components | `apps/site/src/components/` | Create or replace portal UI components. | | Auth logic | `apps/site/src/lib/auth/` | Customize authentication flows. | | Data access | `apps/site/src/lib/dal/` | Add server functions that access the Portal SDK or database. | | Shared UI | `packages/ui/` | Customize components shared across the portal. | ### Add an Authentication Extension[​](#add-an-authentication-extension "Direct link to Add an Authentication Extension") The released Boilerplate routes Better Auth requests through `apps/site/src/routes/api/auth/$.ts`. Add a Better Auth plugin in `apps/site/src/lib/auth/server.ts`, then expose any HTTP methods the plugin needs from the route handler. For example, the current route delegates these methods to `auth.handler`: apps/site/src/routes/api/auth/$.ts ``` const handler = ({ request }: { request: Request }) => auth.handler(request); export const Route = createFileRoute('/api/auth/$')({ server: { handlers: { GET: handler, POST: handler, PUT: handler, PATCH: handler, DELETE: handler, }, }, }); ``` If an extension changes the Better Auth database schema, regenerate the schema and migration, review the generated SQL, and apply the migration before deploying the new application version. ## Portal SDK[​](#portal-sdk "Direct link to Portal SDK") The [Portal SDK](https://github.com/api7/portal-sdk-typescript) (`@api7/portal-sdk`) is pre-integrated in the default Boilerplate and provides a TypeScript client for the Portal API. You can also use it independently to build custom integrations. The SDK README covers installation and usage, not the underlying endpoints. For the full request and response contract, see the [Developer Portal API reference](https://docs.api7.ai/api7-gateway/reference/developer-portal-api.md). ### Server-Side Usage[​](#server-side-usage "Direct link to Server-Side Usage") ``` import { API7Portal } from '@api7/portal-sdk'; const client = new API7Portal({ endpoint: 'https://api7-portal-api.example.com', token: 'a7prt-...', getDeveloperId: async () => await getDeveloperIdFromSession(), }); const products = await client.apiProduct.list(); ``` ### Call the SDK from Server Functions[​](#call-the-sdk-from-server-functions "Direct link to Call the SDK from Server Functions") Portal SDK `2.0.0` exposes its client from `@api7/portal-sdk`; it does not provide the older `@api7/portal-sdk/browser` export. Keep the Portal API token on the server and call the SDK from code under `apps/site/src/lib/dal/` or another TanStack Start server function. Return only the data required by the browser component. For the complete SDK API reference and usage examples, see the [Portal SDK repository](https://github.com/api7/portal-sdk-typescript). ## Building and Deploying[​](#building-and-deploying "Direct link to Building and Deploying") After making customizations, build and deploy the application: ``` # Install dependencies pnpm install # Build the application pnpm build # Or build a Docker image docker build -t my-developer-portal . ``` The Dockerfile in the Boilerplate repository is pre-configured for production builds. ## Additional Resources[​](#additional-resources "Direct link to Additional Resources") * [API7 Developer Portal Boilerplate](https://github.com/api7/api7-portal-boilerplate) * [Developer Portal API reference](https://docs.api7.ai/api7-gateway/reference/developer-portal-api.md) — REST contract called by every portal frontend. * [Portal SDK (TypeScript)](https://github.com/api7/portal-sdk-typescript) * [Better Auth Documentation](https://www.better-auth.com/docs) * [TanStack Start Documentation](https://tanstack.com/start/latest) * [Deploy the Developer Portal](https://docs.api7.ai/api7-gateway/developer-portal/deploy/deploy-portal.md) * [Configure the Developer Portal](https://docs.api7.ai/api7-gateway/developer-portal/deploy/configure-portal.md)