Skip to main content
API7.ai Logo
Version: 3.10.x

Customize the Developer Portal

The API7 Developer 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​

Logo and Site Icon​

Replace the following files with your organization's assets:

AssetFile PathPurpose
Site iconapps/site/public/favicon.icoBrowser tab icon and the default header logo

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​

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​

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​

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://<PORTAL_DOMAIN>/api/auth/callback/<provider>.

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​

The Boilerplate provides several extension points:

Extension PointLocationDescription
Routesapps/site/src/routes/Add pages and server routes with TanStack Router file-based routing.
Componentsapps/site/src/components/Create or replace portal UI components.
Auth logicapps/site/src/lib/auth/Customize authentication flows.
Data accessapps/site/src/lib/dal/Add server functions that access the Portal SDK or database.
Shared UIpackages/ui/Customize components shared across the portal.

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​

The Portal SDK (@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.

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​

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.

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​