API Services Portal

The API Services Portal is a multi-tenant frontend from BC Government that lets API providers manage the lifecycle of their APIs and developers discover and access them, pairing a React/Next.js web application with Kong Gateway and Keycloak for authorization.

What is the API Services Portal?

The API Services Portal is an open-source web application that functions as a frontend for API providers to manage the lifecycle of their APIs and for developers to discover and access those APIs. It runs alongside the Kong Community Edition Gateway and Keycloak IAM solution, and is built with React, Next.js, KeystoneJS V5, and the Chakra UI component library. The repository is maintained by BCGov, the British Columbia government's GitHub organization, and is licensed under an open-source license.

Key Features

• KeystoneJS data model — The aggregation of the application's data is defined in src/lists/* using KeystoneJS lists, covering namespaces, products, services, consumers, and authorization profiles.
• Next.js frontend with Chakra UI — The UI lives in src/nextapp/*, uses TypeScript, and follows the BC Government Web Design System via a custom Chakra theme with variants for core components.
• OAuth2-Proxy authentication — The portal supports OAuth2 flows via an OAuth2-Proxy (v7.8.1) that passes a token to the KeystoneJS backend; middleware verifies the token and initiates a session.
• Authorization rules engine — A decision matrix in src/authz centralizes access rules based on UMA Namespace resources and Permissions from a Requesting Party Token (RPT) held in the KeystoneJS session.
• Ingestor and feeders — An ingestion framework (src/batch/feedWorker.js) pulls content from external sources, with supported feeders for CKAN, Kong, and Prometheus.
• GraphQL type generation — TypeScript types are generated from the GraphQL schema via codegen, producing queries.types.ts in src/nextapp/shared/types.
• Storybook component preview — Custom components are documented and previewable with Storybook, run via npm run storybook.
• Mock server — A GraphQL mock server (npm run mock-server) provides fake data for development and testing, though it does not replicate the production API 1-to-1.

Who is it for?

• API providers — Teams that manage their own namespaces and products; they can view configuration and metrics, grant or revoke consumer access, and publish gateway configuration when they hold the GatewayConfig.Publish permission.
• Application developers — Developers inside or outside the BC government who need to discover available APIs, request access, and consume both public and private documentation.
• Platform administrators — Users responsible for onboarding new namespaces, approving consumer requests, and maintaining the authorization profiles and activity logs for their namespaces.

What can you do with it?

• Publish and manage APIs — Create namespaces and products, define environments, and configure services with the permission model; actions like creating a namespace require only authentication, while deleting requires Namespace.Manage or ownership.
• Request and control API access — Developers can request access to APIs as guests or authenticated users, while resource owners can grant, revoke, approve, or reject consumer access through the My Resources section.
• Monitor and configure gateways — Users with the right permissions can view service configurations and metrics, publish gateway config, and delete gateway config, all gated by UMA namespace permissions.

How does it work?

The portal is split into six components: the KeystoneJS data model, the Next.js UI, OAuth2-Proxy authentication, the authorization engine, an ingestor, and feeders. Locally, docker compose spins up Postgres, Keycloak, OAuth2-Proxy, the Gateway Admin API (gwa-api), and Kong Gateway, exposing the portal at http://oauth2proxy.localtest.me:4180 with test users janis@idir and local.

FAQ

What frameworks does the API Services Portal use?

It uses React with the Next.js framework for the frontend, KeystoneJS V5 for the backend data model, and Chakra UI for components. The client-side app is written in TypeScript, and GraphQL types are generated automatically in development mode.

How do I run the portal locally?

Clone the repo, build the Gateway Admin API from the gwa-api repo, then run docker compose build and docker compose up. The portal will be available at http://oauth2proxy.localtest.me:4180, and you can log in with the test credentials listed in the README.

What is the role of Keycloak in the portal?

Keycloak provides identity and access management. It is initialized with a master realm (configuration in local/keycloak/master-realm.json) and a realm user local with admin privileges. Keycloak issues tokens that OAuth2-Proxy exchanges for the portal's authentication flow.

Does the mock server replicate production data exactly?

No, the mock server is designed to fake data via GraphQL for development and testing. It replicates requests and confirms expected behavior, but a 1-to-1 replication of the production API is not its goal. When Keystone-level types change, you must manually update the mock server schemas.