Can I edit an existing ApiConfig to change a backend address?

No, ApiConfigs are immutable after creation. You create a new ApiConfig with the updated OpenAPI document and then update the Gateway resource's apiConfig reference to point at the new one. This is what makes instant rollback possible, the old ApiConfig still exists and you can just repoint the Gateway back at it.

Why does every request through the gateway return 403 even though my OpenAPI spec looks correct?

This is almost always the gatewayServiceAccount missing the invoker role on the backend. The service account named in apiConfig.gatewayServiceAccount needs roles/run.invoker (for a Cloud Run backend) or the equivalent for Cloud Functions/App Engine, since the managed gateway proxy authenticates to your backend as that identity on every call.

Is the managedService name something I choose?

No, it's assigned by Google when the Api resource is created, following the pattern - .apigateway. .cloud.goog. You reference it as-is; it's the underlying Service Management resource the gateway config is registered against, not a value you get to pick.

GCP API Gateway v2 Config Builder

ServerlessGCP

Build API Gateway v2 configurations with OpenAPI specs, gateway service accounts, and backend routing.

API Gateway Configuration

Build API Gateway v2 configurations with API definitions, OpenAPI specs, gateway service accounts, and backend routing.

Required Fields

api.nameapiConfig.nameapiConfig.gatewayServiceAccountgateway.namegateway.apiConfig

{
  "api": {
    "name": "projects/my-project/locations/global/apis/orders-api",
    "displayName": "Orders API",
    "managedService": "orders-api-abcdef123.apigateway.my-project.cloud.goog",
    "labels": {
      "team": "order-platform",
      "version": "v2"
    }
  },
  "apiConfig": {
    "name": "projects/my-project/locations/global/apis/orders-api/configs/v2-config",
    "displayName": "Orders API v2 Config",
    "gatewayServiceAccount": "api-gw-sa@my-project.iam.gserviceaccount.com",
    "openapiDocuments": [
      {
        "document": {
          "path": "openapi.yaml",
          "contents": "swagger: '2.0'\ninfo:\n  title: Orders API\n  version: '2.0'\nhost: orders-api.endpoints.my-project.cloud.goog\nschemes:\n  - https\nproduces:\n  - application/json\npaths:\n  /orders:\n    get:\n      operationId: listOrders\n      x-google-backend:\n        address: https://orders-service-abc123-uc.a.run.app\n      security:\n        - api_key: []\nsecurityDefinitions:\n  api_key:\n    type: apiKey\n    name: x-api-key\n    in: header"
        }
      }
    ]
  },
  "gateway": {
    "name": "projects/my-project/locations/us-central1/gateways/orders-gateway",
    "displayName": "Orders Gateway",
    "apiConfig": "projects/my-project/locations/global/apis/orders-api/configs/v2-config",
    "labels": {
      "environment": "production"
    }
  }
}

Generated Output

Output will appear here...

About This Tool

Build an API Gateway v2 configuration spanning the Api, ApiConfig, and Gateway resources: the Api is the logical container, the ApiConfig holds an immutable OpenAPI document plus the gatewayServiceAccount that the managed proxy uses to invoke your backend, and the Gateway is the deployed, regional instance serving traffic. ApiConfigs are immutable once created, updating a route or backend address means creating a brand-new ApiConfig and pointing the Gateway at it, not patching the existing one, which is a deliberate versioning/rollback design rather than an oversight.

Real-World Scenario

An API team ships a v2 ApiConfig with an updated OpenAPI spec pointing at a new backend service, but every request starts failing with 403 immediately after the Gateway repoints, because the new backend is a different Cloud Run service and the existing gatewayServiceAccount was never granted invoker on it. They use the builder to lay out the full three-resource chain, catch that apiConfig.gatewayServiceAccount needs an explicit IAM binding on the new backend before cutover, grant roles/run.invoker to that service account, and the same ApiConfig starts serving traffic cleanly on retry.

When to Use This Tool

•Rolling out a backend URL change by creating a new ApiConfig (v3-config) and repointing gateway.apiConfig at it, keeping v2-config around untouched so a rollback is just pointing the Gateway reference back.
•Debugging a 403 on every route because gatewayServiceAccount lacks the roles/run.invoker binding on the backend Cloud Run service the x-google-backend extension targets.
•Adding a new path to the OpenAPI document's x-google-backend.address per operation, since API Gateway routes purely off what's declared in the spec, not a separate routing table.
•Scoping labels on the Api resource by team and version so a bulk cost or ownership audit across dozens of gateways doesn't require opening each one individually.

Pro Tips

TIP

An OpenAPI document with a syntax error or unsupported extension fails ApiConfig creation with an error that can be vague, validate the raw YAML/JSON with a standalone OpenAPI linter before submitting it through this flow to isolate spec bugs from IAM bugs.

TIP

Because ApiConfigs are immutable, every iteration during active development creates a new one, clean up stale ApiConfigs periodically or the Api resource accumulates dozens of unused configs that make the 'which one is live' question harder to answer during an incident.

TIP

The x-google-backend address must be reachable from Google's managed infrastructure, a Cloud Run service with ingress locked to "internal" will reject the gateway's calls even with correct IAM, since ingress control and IAM invoker permission are enforced independently.

How It Works Under the Hood

The builder requires api.name, apiConfig.name, apiConfig.gatewayServiceAccount, gateway.name, and gateway.apiConfig to all resolve, reflecting that a Gateway resource is only valid once it references a real ApiConfig, which in turn is only valid once it references a service account with actual invoke permission on the backend, three linked resources rather than one flat config.

Frequently Asked Questions

Can I edit an existing ApiConfig to change a backend address?: No, ApiConfigs are immutable after creation. You create a new ApiConfig with the updated OpenAPI document and then update the Gateway resource's apiConfig reference to point at the new one. This is what makes instant rollback possible, the old ApiConfig still exists and you can just repoint the Gateway back at it.
Why does every request through the gateway return 403 even though my OpenAPI spec looks correct?: This is almost always the gatewayServiceAccount missing the invoker role on the backend. The service account named in apiConfig.gatewayServiceAccount needs roles/run.invoker (for a Cloud Run backend) or the equivalent for Cloud Functions/App Engine, since the managed gateway proxy authenticates to your backend as that identity on every call.
Is the managedService name something I choose?: No, it's assigned by Google when the Api resource is created, following the pattern <api-id>-<hash>.apigateway.<project>.cloud.goog. You reference it as-is; it's the underlying Service Management resource the gateway config is registered against, not a value you get to pick.

Related Learning Guides

Cloud Functions vs Cloud Run24 min read
Pub/Sub & Event-Driven Architecture25 min read

Was this tool helpful?

Disclaimer: This tool runs entirely in your browser. No data is sent to our servers. Always verify outputs before using them in production. AWS, Azure, and GCP are trademarks of their respective owners.