Version: latest

Customize the Developer Portal

The Developer Portal is built on the API7 Developer Portal Boilerplate, a Next.js application that can be customized to match your organization's branding and requirements. This guide covers the most common customizations.

Branding

Logo and Favicon

Replace the following files with your organization's assets:

Asset	File Path	Purpose
Favicon	`apps/site/app/favicon.ico`	Browser tab icon
Logo	`apps/site/public/logo.svg`	Header 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 for all available variables */
}

note

Branding changes (logo, favicon, 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.

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 OAuth

For identity providers not covered by the built-in social providers, use the generic OAuth plugin. This requires code changes in apps/site/src/lib/auth/server.ts. See the Better Auth OAuth documentation for details.

Extending Functionality

The boilerplate provides several extension points:

Extension Point	Location	Description
Pages	`apps/site/app/`	Add or modify Next.js pages using the App Router.
Components	`apps/site/components/`	Create custom UI components.
Auth logic	`apps/site/src/lib/auth/`	Customize authentication flows.
API routes	`apps/site/app/api/`	Add custom backend endpoints.

Adding SCIM Support

To enable SCIM provisioning with an identity provider like Okta:

Install the SCIM plugin:
```
pnpm add @better-auth/scim@<version>
```
Ensure the version matches your better-auth version.

import { scim } from '@better-auth/scim';

export const auth = betterAuth({
  plugins: [
    // ...existing plugins
    scim(),
  ],
});

Update the route handler in apps/site/app/api/auth/[...all]/route.ts to support SCIM HTTP methods:
```
export const { GET, POST, PUT, PATCH, DELETE } = toNextJsHandler(auth.handler);
```

Run database migrations:

pnpm db:generate-schema && pnpm db:generate && pnpm db:migrate

Generate a SCIM token and configure it in your identity provider.

Portal SDK

The Portal SDK (@api7/portal-sdk) is pre-integrated in the boilerplate and provides a TypeScript client for the Portal API. You can also use it independently to build custom integrations.

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.

Branding​

Logo and Favicon​

Application Name and Description​

Theme​

Authentication Customization​

Email and Password​

Social Login Providers​

Generic OAuth​

Extending Functionality​

Adding SCIM Support​

Portal SDK​

Server-Side Usage​

Client-Side Usage​

Building and Deploying​

Additional Resources​