Skip to main content

Configuration

This section will guide you through the process of configuring your Foundation app.

Foundation App​

Foundation app: Tooling-agnostic. Only requires Kraken API configuration. You're free to choose your own CMS, UI library, analytics, payment processing, and error tracking tools based on your project needs.

App configuration​

The Foundation app has an app.config.ts file in its src folder. This file allows you to customize various aspects of your app, such as the name, description, port, supported languages, and more.

Note: Some values in app.config.ts are sourced from the sibling file app.i18n.json, as they are referenced in JavaScript files like next-i18next.config.js and next-sitemap.config.js.

Environment variables​

To configure the different services used in your application, create a duplicate of the .env.example file and rename it to .env.local in the root of your app.

There is no specific order in which you need to configure the services.

Language switcher​

The language switcher is visible by default. To remove it from the header, set:

NEXT_PUBLIC_REMOVE_LANGUAGE_SWITCHER=true

Only the exact value true removes the switcher. Because this is a public build-time variable, rebuild and redeploy the app after changing it.

Kraken​

Foundation needs Kraken configuration for API access and authentication. Add the variables required by your app to .env.local and to your deployment platform.

The URL examples below use fictional domains. Opaque IDs and credentials use descriptive placeholders because their format is not meaningful. Replace every value with one issued for your app and Kraken environment.

App and API connection​

Configure the app's public URL and Kraken endpoints:

NEXT_PUBLIC_URL="https://foundation.example.com"
KRAKEN_GRAPHQL_ENDPOINT="https://api.xxxx-kraken.systems/v1/graphql/"
KRAKEN_AUTH_ENDPOINT="https://auth.xxxx-kraken.systems/"

Ask your Kraken Client Delivery Lead for the exact GraphQL and authentication endpoints for your Kraken instance and environment:

  • NEXT_PUBLIC_URL is the public origin of your app, without a trailing slash.
  • KRAKEN_GRAPHQL_ENDPOINT is the full Kraken GraphQL API URL, including the /v1/graphql/ path.
  • KRAKEN_AUTH_ENDPOINT is the Kraken authentication base URL.

OAuth authentication​

Configure the trusted access token issuers and OAuth client:

 KRAKEN_ACCESS_TOKEN_ISSUERS="https://api.xxxx-kraken.systems/v1/graphql/,https://auth.xxxx-kraken.systems/token/,https://support.xxxx-kraken.systems"
KRAKEN_OAUTH_CLIENT_ID="<your Kraken OAuth client ID>"

KRAKEN_ACCESS_TOKEN_ISSUERS must contain the exact issuers for your Kraken environment as one comma-separated value with no spaces. Matching is case-sensitive, and paths and trailing slashes are significant. For OAuth, include the auth endpoint's token/ issuer.

Create the OAuth client​

If you have access to the client's Kraken support site and the OAuth manager role:

  1. Open Auth and security at /api-tools/auth-security/.
  2. Open Configure OAuth applications (or go to /api-tools/oauth/ directly).
  3. Select Create, then Customer access.
  4. Enter a recognisable name, select Authorization code grant, and choose Public client.
  5. Add https://<your-app-domain>/api/auth/kraken-oauth to the allowed redirect URIs.
  6. Leave additional permissions empty, enable Should receive refresh tokens, and create the application.
  7. Copy the generated client ID into KRAKEN_OAUTH_CLIENT_ID.

Client IP forwarding​

Configure the client IP secret:

KRAKEN_X_CLIENT_IP_SECRET_KEY="<your Kraken X-Client-IP secret key>"

This secret lets Kraken trust the client IP forwarded by your app’s server. Kraken can then apply IP-based checks to individual users, rather than treating everyone as coming from the same server IP. Rate limits still apply.

Treat this value as a secret: keep it only in .env.local and your deployment platform's encrypted environment variables. Never commit it to source control.

Organization authentication​

Foundation includes organization-scoped authentication for unauthenticated server-side operations such as onboarding. Its current implementation uses Vercel Global Config as a shared token cache.

Shared token cache​

GLOBAL_CONFIG="https://global-config.vercel.com/<store-connection>"
VERCEL_AUTH_TOKEN="<Vercel API token with Global Config write access>"
VERCEL_TEAM_ID="<Vercel team ID>"

Connect a Global Config store to the Vercel project. If you deploy elsewhere, replace src/lib/auth/cache.ts with a shared cache adapter for your platform before using organization-scoped authentication.

Vercel adds GLOBAL_CONFIG when you connect the store. Create VERCEL_AUTH_TOKEN in your Vercel account and ensure it can write to the store owned by VERCEL_TEAM_ID.

Organization API key​

KRAKEN_ORGANIZATION_KEY="<your Kraken organization API key>"

To get KRAKEN_ORGANIZATION_KEY, you need access to the client's Kraken support site and the API organisation manager role:

  1. Open Auth and security at /api-tools/auth-and-security/.
  2. Open Manage organisations at /api-tools/api-organisations/.
  3. Select Create, then enter the organisation name and contact email.
  4. In API keys, select Create API key.
  5. Copy the generated key into KRAKEN_ORGANIZATION_KEY and store it in your approved secret manager.
  6. Go to the Roles section, click Edit and assign the Account Manager and Can query quotes and switch products (or something similar, it can be worded differently) roles to the API key so that the quote journey can be completed.

Token encryption​

Generate a random token encryption key and add the output to your environment:

openssl rand -base64 32

Set the output as AUTH_ENCRYPTION_KEY.

Scheduled token refresh​

The current Foundation app does not include a scheduled organization-token refresh route. If you add one using createUpdateOrgTokenHandler, generate a cron secret and add its output to your environment:

openssl rand -base64 16

Set the output as CRON_SECRET.

Treat the organization key, encryption key, Vercel API token, and cron secret as sensitive credentials. Never expose them to client-side code, commit them to source control, or reuse them across environments.