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

Configure the Developer Portal

After deploying the Developer Portal, use the Provider Portal for supported settings such as public access and portal tokens. The released Provider Portal does not expose authentication or SCIM controls in this line, while email-and-password customization and SCIM require a source-customized frontend.

Portal Settings​

Portal settings are managed in the Provider Portal under each portal's Settings page. The settings are organized into the following sections.

Public Access​

The Public Access toggle controls whether the Developer Portal is accessible to unauthenticated users:

  • Enabled: Unauthenticated visitors can browse the API Hub and view public API products.
  • Disabled: All visitors must authenticate before accessing any portal content.

Portal Tokens​

Portal tokens authenticate the Developer Portal application with the Portal API. Each token has the prefix a7prt and can be configured with an expiration date.

OperationDescription
GenerateCreate a new token with a name and optional expiration date. The token value is shown only at creation time.
RenameUpdate the display name of a token.
RegenerateGenerate a new token value, invalidating the previous one. Update the Developer Portal config.yaml with the new token and restart the application.
DeleteRemove a token. If the Developer Portal is using this token, it will lose connectivity to the Portal API.
caution

After regenerating or deleting a token, update the config.yaml on the Developer Portal host and restart the application. The portal will not function correctly without a valid token.

Built-in Authentication Status​

The released Provider Portal does not expose controls for self-registration, registration approval, email login, or enabling or disabling built-in authentication. The Console source retains code that would read and write these controls through /api/portal/login_options, but the released control plane does not register that route. Do not rely on this unavailable Provider Portal workflow in this released line.

caution

Do not attempt to disable or replace the working email-and-password path through the Provider Portal. Contact API7 Support for the status of the route mismatch in your installed patch.

A source-customized frontend can configure email-and-password behavior through auth.emailAndPassword in config.yaml; see Customize the Developer Portal. Test registration and login in the customized deployment before relying on it for developer access.

SSO (External Login Options)​

External identity providers are intended to provide additional Developer Portal login options. The released Console and control plane currently expose conflicting API contracts for this configuration. See Developer Portal SSO Status before attempting to configure an external provider.

SCIM Provisioning​

SCIM (System for Cross-domain Identity Management) can provision identities from an external identity provider into a custom Developer Portal. The released frontend does not register a SCIM plugin, so the endpoint is not enabled by changing a Provider Portal setting.

For a custom implementation based on Developer Portal Boilerplate v0.10.0, follow Configure SCIM Provisioning for a Custom Developer Portal with Okta. That workflow adds the server plugin, updates the auth route, and migrates the frontend authentication database. SCIM does not configure interactive sign-in or account linking, and provisioned identities do not automatically receive portal organization membership or access to API products. Integrate and test those authentication and authorization paths separately in the custom application.

Application Configuration​

The following settings are configured in the Developer Portal's config.yaml file and require a restart to take effect.

Portal API Connection​

config.yaml
portal:
  url: https://<CONTROL_PLANE_HOST>:4321   # Portal API endpoint
  token: a7prt-xxxxxxxxxxxx                 # Portal token from Provider Portal

Database​

config.yaml
db:
  url: "postgres://user:password@host:5432/dbname"

The Developer Portal uses a PostgreSQL-compatible database for storing user sessions, authentication data, and organization information.

Authentication Secret​

config.yaml
auth:
  secret: "<base64-encoded-secret>"

This secret is used to sign authentication sessions. Generate it with:

openssl rand -base64 32

Application URLs​

config.yaml
app:
  name: "My Developer Portal"        # Displayed in browser title and header
  desc: "API documentation portal"   # Used for SEO meta description
  baseURL: "https://portal.example.com"
  trustedOrigins:
    - "https://portal.example.com"

Environment Variable Substitution​

Configuration values support environment variable substitution:

SyntaxBehavior
${VAR}Required. Fails if the variable is not set.
${VAR:default}Optional. Uses the default value if the variable is not set.

Example:

config.yaml
portal:
  url: ${PORTAL_API_URL}
  token: ${PORTAL_TOKEN}
auth:
  secret: ${AUTH_SECRET}

Additional Resources​