Skip to content

Scopes and claims

TrustNet separates protocol capabilities (scopes) from user data (claims).

Scopes

Scope Required What it means
openid yes OIDC authentication. The machine plane also requires it on the access token.
offline_access no Requests a refresh token and ongoing access. The consent screen discloses ongoing access separately.

New registrations may use only these two scopes. The legacy profile, email and phone scopes remain supported for older integrations; new integrations declare claims instead.

Claim catalog

The RP may declare and request only the names below. sub is always present and is not a declared claim.

Claim Type Source
name string Persona attribute
given_name string Persona attribute
family_name string Persona attribute
middle_name string Persona attribute
nickname string Persona attribute
preferred_username string Persona attribute
profile string (URL) Persona attribute
picture string (signed URL) Persona picture or generated avatar
website string (URL) Persona attribute
email string Persona attribute
gender string Persona attribute
birthdate string (YYYY-MM-DD) Persona attribute
zoneinfo string Persona attribute
locale string Persona attribute
phone_number string Persona attribute
email_verified boolean Derived from the account's verified contact state
phone_number_verified boolean Derived from the account's verified contact state
over_18 boolean Derived from birthdate

Not requestable:

  • address — structured object; not part of the flat claim catalog yet.
  • sub — always present, system-generated PPID.
  • updated_at — system metadata.

picture is always a short-lived signed URL when disclosed; it never exposes a storage key or file reference.

Requesting claims

Declare claims at registration, each with a non-empty reason shown to the user at consent. Request them per transaction with the standard claims parameter:

{
  "id_token": {
    "email": null,
    "email_verified": null,
    "given_name": null,
    "family_name": null,
    "picture": null
  }
}

Rules:

  • A claim not declared at registration is dropped and never disclosed.
  • A null detail is a voluntary request; "essential": true is advisory only and never forces disclosure.
  • TrustNet unions the id_token and userinfo targets when deciding what to offer. The user's approval, not the target, decides what is disclosed.
  • A claim the chosen persona does not hold, or the user does not approve, is absent from the response.
  • email_verified and phone_number_verified are computed at disclosure; they are not injected by a scope.

The claim names match the OIDC standard claim names and the product's attribute catalog, so a claim a persona holds is always requestable under the same name.