org_id, tenant_id, workspace_id: which claim should you use?

Different SaaS auth providers use different claim names for the same concept. Here's when to use each, and how to migrate between them.

Last updated: May 2026

shield

Private: Decoding, analysis, signature verification, and token generation all run in your browser. Nothing is sent to any server, except a JWKS URL you explicitly enter and click Verify on.

Paste your JWT

At a glance

Clerk / WorkOS / Auth0 (Organizations): org_id
Stack Auth: selected_team_id
Firebase (GCIP): firebase.tenant
Supabase: app_metadata.tenant_id
AWS Cognito: custom:tenant_id
Custom JWTs: tenant_id (recommended)

Multi-tenant claim names vary by auth provider: Clerk and WorkOS use `org_id`, custom apps often use `tenant_id`, Stack Auth uses `selected_team_id`, Supabase nests it under `app_metadata`, and Cognito uses a `custom:` prefix. The names differ but the concept is the same. Here's how to pick a convention and stay portable across providers.

Why the names differ

There's no JWT spec for tenant claims. RFC 7519 defines a small set of registered claim names (iss, sub, aud, exp, iat, nbf, jti) and leaves everything else to applications. Each auth provider picked the name that fit their product's terminology — Clerk and WorkOS think in terms of "organizations", Stack Auth in "teams", Supabase in metadata blocks.

The result is that a generic JWT debugger has no way to know that `org_id` and `selected_team_id` mean the same thing. This tool maintains a registry of equivalent claim names, so the Summary card reads naturally regardless of which provider issued the token.

Frequently asked questions

Which name should I use for a custom JWT?expand_more

`tenant_id` is the most provider-agnostic. It's also the term most engineers reach for first when describing multi-tenant systems, so the code you write reads naturally. If your product's user-facing terminology is "organization" or "workspace", match that — claim names should match the language your team and customers already use.

Can I use multiple tenant claims for compatibility?expand_more

Yes — and many auth providers do. You can populate both `tenant_id` and `org_id` with the same value if your codebase has middleware that expects different names. Just be sure to keep them in sync at issue time so they don't drift.

How do I migrate from one tenant claim name to another?expand_more

Issue tokens with both claims simultaneously for one full token-lifetime cycle. Update consumers to read the new claim, but tolerate the old. Once all live tokens have rotated and all consumers are reading the new name, drop the old claim from new tokens.

Why conflating tenant identity with user identity in the sub claim is a multi-tenant anti-pattern, and the conventions that work instead.

JWT permissions: scopes, roles, and how to encode them

Resource:action strings, OAuth scopes, bitmasks — which permission encoding to use in a multi-tenant JWT, and the trade-offs of each.