Administrator claims — is_app_admin and is_tenant_admin

Audience: teams building an application that signs users in through HAP and needs to know whether the person signing in is an administrator.

Status: live. This page is the definitive contract — if anything elsewhere disagrees with it, this page is right and the other page is stale.

HAP is the authority on who is an administrator. Your application does not have to re-derive it, mirror it, or invent it — and specifically does not need to fall back on rules like "the first user to sign in becomes the admin", which on a shared installation hands the application to whoever opens it first.

1. The two claims

Every id token and every userinfo response carries both of these, for every application:

{
  "sub": "0a1b2c3d-…",
  "email": "someone@example.com",
  "is_app_admin": true,
  "is_tenant_admin": false
}

Three properties you can rely on:

1. Always present. Both claims appear on every response, true or false. They are never omitted, so an absent claim means you are talking to something that is not this version of HAP — not that the answer is "no".
2. No scope required. You do not request them, and you do not re-register your application. openid is enough to get an id token; userinfo needs only the access token.
3. Independent. See §2 — this is the part that surprises people.

2. The two claims are independent. HAP asserts no implication between them

A tenant administrator does not automatically get is_app_admin: true.

This is deliberate. HAP reports facts, and the fact reported by is_app_admin is a per-application designation. It is also true that a tenant administrator may administer every application in the tenant — that is how HAP's own authorization works — but folding that into the app-scoped claim would make the claim useless on any installation where several applications share a tenant: everyone who administers anything would read as an administrator of yours.

So the four combinations all occur and all mean something:

Deciding what counts as an administrator in your application is yours, and you must make it explicitly. Most first-party applications want:

const isAdmin = claims.is_app_admin || claims.is_tenant_admin

If instead you want only people designated for your application, use is_app_admin alone. Either is a legitimate model. What is not legitimate is assuming HAP has already made the choice for you.

If your claim-reading code walks a list of candidate claim names and stops at the first one it finds, it will never see is_tenant_admin — is_app_admin is always present, so it always matches first. Read both claims explicitly.

3. Both claims are inert unless the identity is active

A suspended or deleted identity reports false for both, regardless of any designation it holds. Reinstating the identity restores the previous answer; nothing needs re-granting.

This matters because in a tenant without revoke-on-suspend, an access token issued before the suspension stays valid until it expires. Such a token reports no authority.

4. When your copy of the answer goes stale

So a promotion or a revocation reaches an application that only reads the id token at the user's next sign-in. If that is too slow, call userinfo on whatever interval you re-validate sessions; it needs no extra credential.

Note the asymmetry, because the two failure modes are different:

• Suspending or deleting an identity takes effect immediately in tenants with revoke-on-suspend enabled — sessions and refresh tokens die, and the user is signed out at the next refresh.
• Merely removing an administrator designation does not touch the user's session. They keep using the application as an ordinary user, but only once you have re-read the claim.

5. Rolling this out without demoting your existing administrators

If your application already has administrators that HAP does not know about — someone set a flag in your database, or an installation was recovered by hand — read this before you ship a release that trusts the claims.

The claims are unambiguous by design: false means "HAP says this person is not an administrator". If you apply that to a user whose admin rights exist only in your own database, you will demote them. HAP does not know about them and will keep saying false.

Reconcile first. For each existing administrator, designate them in HAP:

On a freshly provisioned tenant: POST /v1/tenants with admin_email designates a tenant administrator before anyone signs in — it does not create a per-application designation. So on a new installation, is_tenant_admin is the claim that has someone in it and is_app_admin is false for everyone. If your application reads is_app_admin alone (§2), designate that person for your application at install time, or nobody will be an administrator.

6. What you should not do

• Do not ask for an admin API key so your application can query the administrators API. An installed application holding platform-administrative credentials is a far larger grant than this question needs. The claims exist so you never have to.
• Do not make the first user to sign in an administrator. It is a competing answer to a question HAP has already settled, and on a shared installation it gives the application away.
• Do not treat a missing claim as false. See §1.

7. Where the answers come from

Neither claim is a new concept — both are surfacing state HAP already held:

• is_tenant_admin is the tenant-administrator designation used by the Admin Console.
• is_app_admin is the per-application administrator designation (an application administrator has full delegated control of one application — its lifecycle, its access entitlements, and its co-administrators — with no tenant-wide authority).

Managing either is documented in entitlement-administration.md and api-reference.md.