Route API traffic by Auth0 JWT claim values

Claim-aware routing: what it enables

A JWT from Auth0 carries more than just an identity assertion. It can carry custom claims — subscription tier, user role, tenant ID, feature flags, geographic region — that are set at token issuance time and signed into the payload.

Using these claims at the gateway layer means you can differentiate how requests are handled without any routing logic in your backend. Different plans get different treatments. Different tenants route to different upstream systems. Different roles access different paths. The gateway reads the claim and acts on it before your backend ever sees the request.

Step 1: Configure Auth0 JWT verification

Create a jwtVerify proxy credential that validates Auth0 JWTs. Set the jwksUri to your Auth0 tenant’s JWKS endpoint, and the audience to the API identifier you configured in Auth0:

POST /clients/{clientId}/credentials
{
  "credentialType": "proxy",
  "credentialAuthType": "jwtVerify",
  "credentialName": "auth0-api-jwt-verify",
  "credentialRegion": "us-east-1",
  "credentialSecret": {
    "jwksUri": "https://your-tenant.us.auth0.com/.well-known/jwks.json",
    "audience": "https://api.myapp.com",
    "issuer": "https://your-tenant.us.auth0.com/"
  }
}

Step 2: Create proxies for each routing target

For claim-based routing, you typically have multiple proxies pointing at different targets — for example, a standard tier backend and a premium tier backend:

POST /clients/{clientId}/proxies
{
  "proxyName": "api-standard-tier",
  "proxyRegion": "us-east-1",
  "proxyProxyCredentialId": "<auth0-api-jwt-verify-id>",
  "proxyTargetId": "<standard-backend-target-id>",
  "proxyTargetCredentialId": "<internal-key-id>",
  "proxyDefaultRuleEffect": "deny",
  "proxyAlias": "api-standard"
}

POST /clients/{clientId}/proxies
{
  "proxyName": "api-premium-tier",
  "proxyRegion": "us-east-1",
  "proxyProxyCredentialId": "<auth0-api-jwt-verify-id>",
  "proxyTargetId": "<premium-backend-target-id>",
  "proxyTargetCredentialId": "<internal-key-id>",
  "proxyDefaultRuleEffect": "deny",
  "proxyAlias": "api-premium"
}

Standard tier callers call api-standard; premium tier callers call api-premium. The routing decision is made by which proxy the client calls — which is determined by the claim in their Auth0 token.

Step 3: Enforce claim requirements per proxy with rules

On each proxy, use authorization rules to deny requests from tokens that carry the wrong tier claim. Because the proxy credential is jwtVerify, rules can inspect decoded JWT claims directly.

On the standard proxy, deny requests from tokens that don’t carry free or standard in the plan claim:

POST /clients/{clientId}/proxies/{standardProxyId}/rules
{
  "effect": "deny",
  "token": [
    {
      "claim": { "pattern": "^https://myapp\\.com/plan$" },
      "value": { "pattern": "^(free|standard)$" },
      "presence": "must_absent"
    }
  ],
  "notes": "Tier check: deny requests without free/standard plan claim on this proxy"
}

Note: Auth0 custom claims must be namespaced (Auth0 requirement for non-registered claims). Use the full namespace in the claim pattern: ^https://myapp\\.com/plan$.

Step 4: Apply different rate limits per tier

Configure rate limits directly on each proxy using proxyMaxRequestsPerMinute and proxyMaxRequestsPerDay. Each proxy enforces its own independent budget, so standard-tier traffic hitting its cap has no effect on premium-tier traffic.

For the standard tier proxy:

PUT /clients/{clientId}/proxies/{standardProxyId}
{
  "proxyMaxRequestsPerMinute": 60,
  "proxyMaxRequestsPerDay": 5000
}

And more generous limits for the premium tier proxy:

PUT /clients/{clientId}/proxies/{premiumProxyId}
{
  "proxyMaxRequestsPerMinute": 300,
  "proxyMaxRequestsPerDay": 20000
}

Step 5: Enforce feature access with claim-based rules

Beyond routing, you can gate specific features within a single proxy using authorization rules. For example, allow the /v1/reports/export endpoint only for enterprise plan tokens:

POST /clients/{clientId}/proxies/{proxyId}/rules
{
  "effect": "allow",
  "methods": ["GET"],
  "path": {
    "path": { "pattern": "^/v1/reports/export$" },
    "presence": "must_exist"
  },
  "token": [
    {
      "claim": { "pattern": "^https://myapp\\.com/plan$" },
      "value": { "pattern": "^enterprise$" },
      "presence": "must_exist"
    }
  ],
  "notes": "Feature gate: export requires enterprise plan claim"
}

With proxyDefaultRuleEffect: "deny", this rule is the only path to the export endpoint — callers without the enterprise plan claim receive a 403 before the request is ever forwarded.

Using tenant ID claims for multi-tenant path enforcement

Auth0 custom claims can carry organisation IDs (especially with Auth0 Organizations enabled). Use the variables system in rules to extract the org ID and enforce tenant isolation at the path level:

POST /clients/{clientId}/proxies/{proxyId}/rules
{
  "effect": "allow",
  "variables": [
    {
      "name": "orgId",
      "source": "jwtClaim",
      "key": "https://myapp.com/org_id"
    }
  ],
  "path": {
    "path": {
      "pattern": "^/v1/organisations/{{orgId}}(/.*)?$"
    },
    "presence": "must_exist"
  },
  "notes": "Org isolation: Auth0 org_id claim must match path org segment"
}

With proxyDefaultRuleEffect: "deny", only requests where the path’s org segment matches the token’s org_id claim are forwarded. Callers cannot access another organisation’s data, regardless of how they construct the URL.

What this doesn’t handle

JWT claim checks operate on the token payload at request time. They don’t:

• Call Auth0 live to verify token revocation (use short expiry times to limit the revocation window).
• Handle claims that are arrays unless the regex is written to match substring patterns.
• Replace application-level business logic for complex multi-step authorization decisions.

Next steps

Auth0 is one of the supported JWT providers for jwtVerify credentials. The same approach works with Okta, Cognito, Entra ID, and any JWKS-compatible provider. Read the RequestRocket JWT and authorization rule documentation or start for free.