Add developer onboarding with Apigee

Use the Apigee plugin to let developers get API keys for your Apigee API products from your developer portal, without the Apigee integrated portal or a support request. Developers register apps, pick API products, share apps in teams, and use their key in Try it on your API reference pages.

The plugin adds these to your project:

• An API keys page where signed-in developers register apps, pick API products, and reveal, copy, add, and delete the consumer keys Apigee issues. A link to the page appears next to the user menu for signed-in users.
• A Teams tab, when you set teams.enabled in redocly.apigee, where developers create teams, invite members, and register apps a team owns. Teams are Apigee app groups, so a team created in the Apigee integrated portal appears as well. Every member can add, edit, and delete the team's apps and keys, and only owners can change the team and its members.
• A Request access button in the sidebar of an API reference page. It changes to Pending approval while a request waits, and to Credentials when the developer has access.
• The developer's key in Try it on the API reference page.
• An optional Approvals tab where reviewers approve or reject requests for products that require approval, with an audit log of each decision.

Apigee stays the source of truth for developers, apps, keys, products, and team members, so a change you make in Apigee shows up on the developer's page. Your project stores only what Apigee can't: the date each member joined a team, the reason a developer gave with a request, and the reviewers' decisions and comments. It never stores key values.

Make sure you have the following:

• An Apigee X or Apigee hybrid organization with API products. Teams use app groups, which Apigee Edge doesn't have.
• A way for developers to sign in to your project, such as sso or idps. Each user needs an email address, because Apigee developers are keyed by it.
• A project that uses version 1.0.0-next.0 or later of the @redocly/framework package. The plugin doesn't work with @redocly/realm or with earlier versions of @redocly/framework.

Use only identity providers that verify email addresses. Anyone who signs in with an email address gets the apps and keys of the Apigee developer with that email.

1. Install the package in your Redocly project:

   pnpm add @redocly/framework-plugin-apigee
   

2. Add the plugin to the plugins list in your redocly.yaml:

   redocly.yaml

   plugins:
     - '@redocly/framework-plugin-apigee/plugin.js'
   

3. Add your Apigee organization name to the redocly.apigee configuration.

A project can use one developer onboarding plugin at a time, because each serves the same page.

If your project has an Apigee adapter in developerOnboarding from classic Realm, Framework reads the first one as redocly.apigee and displays a warning. See Migrate from developerOnboarding to move it.

The plugin calls the Apigee management API as a Google service account, or through an OAuth 2.0 proxy you put in front of the management API. The operations it calls are listed in Apigee API operations used by Redocly.

Create a service account in the Google Cloud project of your Apigee organization and give it the Apigee Developer Admin role. Then set your organization and the key of the service account in redocly.apigee:

redocly.apigee:
  organizationName: museum-prod
  stage: production
  auth:
    type: SERVICE_ACCOUNT
    serviceAccountEmail: portal@museum-prod.iam.gserviceaccount.com
    serviceAccountPrivateKey: '{{ process.env.APIGEE_PRIVATE_KEY }}'

Keep the private key in an environment variable, never in the configuration file. These credentials let anyone who can change your redocly.yaml or preview a branch act on your developers and keys. Give a preview environment other credentials than production, or none.

See redocly.apigee for all the options, and the Apigee auth object for the OAuth 2.0 proxy.

The page is called API keys and lives at /apps. Change either with the title and basePath options of redocly.apigee:

redocly.apigee:
  title: Developer keys
  basePath: /developers/apps

Name the Apigee API product in the x-metadata.apiId field of the info object of your API description:

openapi: 3.1.0
info:
  title: Museum Tickets API
  version: 1.0.0
  x-metadata:
    apiId: museum-tickets

You can also set it in the metadata.apiId option of the API in apis.

The portal then offers the product only to developers who can open the page, links the product to the page on the API keys page, and shows the Request access or Credentials button in the sidebar of the API reference. A product that no page names stays hidden, unless you set apiProducts.allowOutsideCatalog in redocly.apigee. With apiProducts.matchByTitle in redocly.apigee, a product without an apiId also matches the OpenAPI page whose title equals the product's display name.

Try it fills in the apiKey and OAuth 2.0 client credentials security schemes of the API, so declare one in your API description.

A product with approvalType: manual in Apigee leaves a new key pending until someone approves it. Approvals let reviewers do that from the portal. They are off by default, and they need role-based access control.

To turn on approvals, set approvals.enabled in redocly.apigee:

redocly.apigee:
  approvals:
    enabled: true

With approvals on, a developer who picks a product with manual approval enters a reason with the request. The Approvals tab is at /apps/admin, and each reviewer sees the requests and the audit log of the products they can review. The reviewer's comment shows on the developer's key.

Reviewers come from the roles in rbac:

access:
  rbac:
    content:
      '**':
        '*': read
      'openapi/payments.yaml':
        '*': read
        payments-team: maintain
      '/apps':
        authenticated: read
        api-admins: admin

With this configuration, members of payments-team review requests for the product that openapi/payments.yaml names, and members of api-admins review every request. The API keys page follows your rbac rules like any other page. A developer needs at least the read role on it, and nobody can open it if no rule matches it. Signed-out visitors who can read the page see a prompt to sign in.

Because this feature is experimental, expect its options and pages to change. It has these known limits:

• The page and the button don't appear in the preview that runs in your browser in the Redocly editor, because plugins don't run there. They appear in the previews and sites that Redocly builds.
• The plugin connects to one Apigee organization.
• Teams are off unless you set teams.enabled in redocly.apigee, and they need Apigee X or Apigee hybrid.
• The pages are in English only.
• Try it keeps the filled-in key in browser storage after sign-out, as it does for every secret. The next person on that browser can see it.
• A developer's key replaces the values your project sets with configure or useConfigureReplay in Try it.

• redocly.apigee - Reference for the plugin options: the Apigee organization, the API keys page, approvals, API products, and teams
• developerOnboarding - The classic Realm adapters and the Apigee auth objects
• Apigee API operations used by Redocly - The management API operations the plugin calls, for a custom authorization proxy
• rbac - Give teams the roles that review requests
• sso - Choose how developers sign in to your project