Skip to content

Call UserInfo

UserInfo returns sub and the claims the user approved for the token's persona. There are two equivalent surfaces:

Surface URL Use
OIDC UserInfo https://id.trustnet.app/userinfo Standard OIDC clients, browser or backend.
RP machine plane https://rp.trustnet.app/api/rp/v1/userinfo Server-to-server integrations that already hold the access token.

Both use the access token issued at consent. The token is opaque; send it as a bearer credential and never try to decode it.

Call the OIDC UserInfo endpoint

curl -sS "https://id.trustnet.app/userinfo" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json"

Call the machine plane

curl -sS "https://rp.trustnet.app/api/rp/v1/userinfo" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json"

On local staging, use https://rp.stg.trustnet.test/api/rp/v1/userinfo.

Response

The response is a JSON object containing sub and the approved claims:

{
  "sub": "<PPID for this RP and persona>",
  "email": "<the user's approved email>",
  "email_verified": true,
  "given_name": "<the user's approved given name>"
}

Only the claims approved at consent are returned. A requested claim can be absent if the persona does not hold it or the user did not approve it.

The OIDC UserInfo response also carries standard metadata such as iss, aud, iat and auth_time. The machine plane returns sub and the approved claims only.

The machine plane records every successful read as a disclosure event — claim names only, never values — so the user can see it in their access history.

Rules and failure modes

  • The token must be active and have the openid scope.
  • The token is scoped to one persona. If the user switches persona, use the new token; never mix claims from two personas.
  • Do not cache responses containing PII beyond the life of the access token. Responses are Cache-Control: no-store for a reason.
  • Do not log tokens, claim values or full responses.
Status Code Meaning What to do
401 invalid_token Missing, expired, revoked or otherwise invalid token. Re-authenticate or refresh; do not retry the same token.
403 insufficient_scope The token does not carry the required scope. Request a token with openid.
502 temporarily_unavailable Upstream verification failed. Retry with backoff.

See Handle errors for the full code set.