What's the difference between a 401 from ESPv2 and a 403 from my own backend?

ESPv2 (the Endpoints proxy) returns 401 when it can't validate the JWT itself — expired token, wrong issuer, signature mismatch against the provider's jwks_uri, or a missing token on a selector that requires one. A 403 from your own code means the token was valid and reached your backend, but your application-level authorization logic rejected the request; those are two entirely separate failure points to debug.

Does the name field have to be a real domain I own?

It has to be either a domain you control and have set up in Cloud DNS, or the auto-generated *.endpoints. .cloud.goog form, which Cloud Endpoints provisions for you automatically and requires no DNS setup at all. Most teams use the endpoints.cloud.goog form for internal services and a real domain only for public-facing APIs.

Why did my quota limit not actually throttle anything?

Quota enforcement requires the caller to be identified as a consumer, typically via an API key, matching the {project} substitution in the unit field. Traffic authenticated only via a JWT provider with no API key attached isn't tied to a quota-metered consumer project, so the limit silently doesn't apply to it — pair quota rules with API key requirements if you need them enforced.

GCP Cloud Endpoints Config Builder

ServerlessGCP

Build Cloud Endpoints OpenAPI service configurations with authentication providers and quota limits.

Cloud Endpoints Configuration

Build Cloud Endpoints OpenAPI service configurations with authentication providers, quota limits, and backend routing rules.

Required Fields

nametitleapisbackend.rules

{
  "type": "google.api.Service",
  "config_version": 3,
  "name": "my-api.endpoints.my-project.cloud.goog",
  "title": "My Production API",
  "apis": [
    {
      "name": "my.api.v1",
      "version": "v1"
    }
  ],
  "authentication": {
    "providers": [
      {
        "id": "firebase",
        "jwks_uri": "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com",
        "issuer": "https://securetoken.google.com/my-project",
        "audiences": "my-project"
      },
      {
        "id": "google_id_token",
        "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
        "issuer": "https://accounts.google.com"
      }
    ],
    "rules": [
      {
        "selector": "my.api.v1.PublicEndpoint",
        "allowWithoutCredential": true
      },
      {
        "selector": "my.api.v1.*",
        "requirements": [
          {
            "providerId": "firebase",
            "audiences": "my-project"
          }
        ]
      }
    ]
  },
  "usage": {
    "rules": [
      {
        "selector": "my.api.v1.*",
        "allowUnregisteredCalls": false
      }
    ]
  },
  "quota": {
    "limits": [
      {
        "name": "read-requests",
        "metric": "read-requests",
        "unit": "1/min/{project}",
        "values": {
          "STANDARD": 1000
        }
      }
    ]
  },
  "backend": {
    "rules": [
      {
        "selector": "my.api.v1.*",
        "address": "https://api-backend-abc123-uc.a.run.app",
        "protocol": "h2"
      }
    ]
  }
}

Generated Output

Output will appear here...

About This Tool

Build a Cloud Endpoints OpenAPI service configuration (the google.api.Service descriptor deployed via `gcloud endpoints services deploy`), covering authentication providers, per-selector auth rules, usage rules, quota limits, and backend routing. The ESPv2 proxy sitting in front of your backend enforces everything declared here: JWT validation against each provider's jwks_uri, the allowUnregisteredCalls gate on anonymous traffic, and quota limits keyed by the {project} substitution so limits apply per API-key-holding consumer rather than globally.

Real-World Scenario

A mobile team adds a new Firebase-authenticated feature and starts seeing intermittent 401s only from Android clients, not iOS, three days after a security team rotated the Firebase signing key as part of a routine credential rotation. Investigating the ESPv2 logs shows JWT signature validation failures that trace back to the jwks_uri cache not having refreshed on some proxy replicas yet. They use the builder to review the authentication.providers block, confirm the jwks_uri is correct, and coordinate a rolling restart of the ESPv2 deployment to force an immediate key refresh instead of waiting out the cache TTL.

When to Use This Tool

•Adding a second authentication provider (google_id_token alongside firebase) so both first-party mobile clients and internal Google-authenticated tooling can call the same API without separate deployments.
•Scoping an authentication rule's selector to my.api.v1.PublicEndpoint with allowWithoutCredential so a health-check or public status route doesn't require a JWT while every other method under my.api.v1.* does.
•Debugging a 401 that only happens for one client, which usually traces back to the audiences value in the provider block not matching the aud claim the client's token actually carries.
•Setting a per-selector quota limit tighter than the API-wide default for an expensive endpoint like a bulk export, so one noisy consumer can't exhaust capacity that other consumers depend on.

Pro Tips

TIP

config_version 3 is the current schema; older Endpoints deployments pinned to version 1 or 2 are missing fields like usage.rules and won't accept some of the newer quota syntax, check the version before copying an example from older documentation.

TIP

jwks_uri is fetched and cached by ESPv2 at startup and on a refresh interval, rotating a provider's signing keys without waiting for that cache to refresh causes a window of spurious 401s for legitimately valid new tokens.

TIP

backend.rules address must be reachable from wherever ESPv2 is actually running (a GKE sidecar, a Cloud Run container, or a Compute Engine instance), a common deploy mistake is leaving the address pointed at a dev backend URL after promoting the config to production.

How It Works Under the Hood

The builder checks that name, title, apis, and backend.rules all resolve before accepting the JSON as a valid Endpoints service config, mirroring the minimum fields `gcloud endpoints services deploy` needs to register a service, an API surface, and somewhere to actually route the traffic it authenticates.

Frequently Asked Questions

What's the difference between a 401 from ESPv2 and a 403 from my own backend?: ESPv2 (the Endpoints proxy) returns 401 when it can't validate the JWT itself — expired token, wrong issuer, signature mismatch against the provider's jwks_uri, or a missing token on a selector that requires one. A 403 from your own code means the token was valid and reached your backend, but your application-level authorization logic rejected the request; those are two entirely separate failure points to debug.
Does the name field have to be a real domain I own?: It has to be either a domain you control and have set up in Cloud DNS, or the auto-generated *.endpoints.<project>.cloud.goog form, which Cloud Endpoints provisions for you automatically and requires no DNS setup at all. Most teams use the endpoints.cloud.goog form for internal services and a real domain only for public-facing APIs.
Why did my quota limit not actually throttle anything?: Quota enforcement requires the caller to be identified as a consumer, typically via an API key, matching the {project} substitution in the unit field. Traffic authenticated only via a JWT provider with no API key attached isn't tied to a quota-metered consumer project, so the limit silently doesn't apply to it — pair quota rules with API key requirements if you need them enforced.

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.