Connect your first gateway

This quickstart is for administrators connecting API-dex to a gateway for the first time. At the end you have one live environment that every user can select in the header, and one permission group that controls who may use it.

Before you begin, you need:

• An API-dex account with the administrator role.
• A service account on the gateway with permission to read its APIs, applications and credentials. The exact fields per gateway are listed under Gateway connection fields.
• Network access from API-dex to the gateway's management API. If the gateway sits behind a firewall or VPN, arrange the route with your network team first.

Register the environment

1

Sign in

Open your API-dex address and sign in with your organisation account.

2

Open Admin → Environments

Open Admin in the main navigation and select Environments.

3

Create the environment

Select New environment. The Create new environment page opens.

4

Choose the gateway

Under Gateway Provider, select Apigee, Azure or Gravitee. The connection fields below change with this choice.

5

Name it

Enter a Display name your users will recognise in the environment switcher, for example "Production – Apigee", and an Environment name used as its identifier, for example prod-gateway.

6

Fill in the connection fields

Enter that gateway's connection fields; see Gateway connection fields. Leave Environment access empty for now.

7

Submit

Select Submit. API-dex saves the environment and it becomes selectable from the environment control in every user's header. If the gateway rejects the credentials, the catalog for the environment stays empty; open the environment again, correct the fields and Save.

Gateway connection fields

• Authentication method: Service account or Workload Identity Federation. Workload Identity Federation uses the identity API-dex runs under instead of a stored key.
• Organization / Region: the name or ID of your Apigee organisation.
• URL of the management API: Global (apigee.googleapis.com), a regional endpoint, or Custom URL (on prem) for Apigee Edge (https://api.enterprise.apigee.com) or hybrid.
• Token URL: the OAuth token endpoint, prefilled for Google Cloud.
• Username and Password: the service account's email and key.

Decide who may use it

1

Create or open a permission group

Open Admin → Permission Groups. Select New permission group for this environment's access pattern, or open an existing one.

2

Link teams

On the Linked Teams tab, select Add team and choose the consumer or backend teams that should have access. Members of those teams inherit it immediately. On the API Access tab, Add API lists the APIs the group grants.

3

Restrict roles if needed

To limit an environment to accounts carrying a role from your identity provider, open the environment and fill in Environment access: the Entry role a user must hold (for example brand-b:member) and the Role prefix that identifies the roles for this environment. This is independent of team and application permissions.

Verify the environment is live

1

Switch to the new environment

From any page, open the environment control in the top bar and select the environment you created. The entry shows its name and gateway type.

2

Open APIs

Any API already published on the gateway appears in the list. A newly connected gateway shows an empty catalog until the first specification is uploaded, which is the next tutorial.

What's next

• Publish your first API: get the first specification into this environment's catalog.
• Reference: admin tools: every field on the Environments and Permission Groups screens.
• How API-dex works: how environments, permission groups and teams relate.