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

Customize the Developer Portal

The Developer Portal can be built from API7 Developer Portal Boilerplate v0.10.0, a customizable Next.js reference implementation aligned with this API7 Gateway release. This guide covers the most common 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/app/favicon.icoBrowser tab icon
Logoapps/site/public/logo.svgHeader logo displayed on all pages

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 with CSS custom properties for theming. Edit apps/site/app/globals.css to customize colors:

apps/site/app/globals.css
:root {
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  /* See globals.css in the Boilerplate repository for all available variables */
}
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, integrate an email provider SDK in apps/site/src/lib/auth/server.ts. Without an email provider integration, setting requireEmailVerification: true will block sign-ups because verification emails cannot be sent.

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 not covered by the built-in social providers, add it to auth.genericOAuthProviders in config.yaml:

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

Boilerplate v0.10.0 registers these entries with the generic OAuth plugin. Generic providers use the callback URL https://<PORTAL_DOMAIN>/api/auth/oauth2/callback/<providerId>. For this example, register https://<PORTAL_DOMAIN>/api/auth/oauth2/callback/keycloak with the provider.

Extending Functionality​

The Boilerplate provides several extension points:

Extension PointLocationDescription
Pagesapps/site/app/Add or modify Next.js pages using the App Router.
Componentsapps/site/components/Create custom UI components.
Auth logicapps/site/src/lib/auth/Customize authentication flows.
API routesapps/site/app/api/Add custom backend endpoints.

Adding SCIM Support​

Boilerplate v0.10.0 does not enable SCIM by default. Adding it requires a SCIM plugin compatible with the Boilerplate's resolved Better Auth 1.6.19 dependency set, additional auth-route methods, a reviewed database migration, and an owner-scoped provisioning credential.

See Configure SCIM Provisioning for a Custom Developer Portal with Okta for the tested user-creation and attribute-update procedure. SCIM 1.6.19 keeps the active attribute read-only and does not establish an Okta deactivation workflow for this baseline, so treat deprovisioning and portal authorization as separate custom integration work.

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();

Client-Side Usage​

import { API7Portal } from '@api7/portal-sdk/browser';

const client = new API7Portal();
const products = await client.apiProduct.list();

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​