How the flow works

Five steps

1. 1

   authorize

   Send the person to GET /v1/oauth/authorize. It redirects to the hosted flow and forwards explicit prompt, max_age and login_hint values. With no prompt, a sufficient existing session and unchanged permissions continue automatically; otherwise authentication or consent is shown.

2. 2

   consent

   UnifyID signs the person in. The first time, it shows them the concrete release — the claim names, each identity document by name, how many contacts leave — with your purpose above it, and approving is a single decision. Someone already connected sees *Continue as* instead, or only the permissions you added. Cancelling returns access_denied.

3. 3

   code

   An authorization code arrives at your registered redirect_uri, with the state you sent. response_types_supported is ["code"]: there is no other response type.

4. 4

   token

   POST /v1/oauth/token exchanges the code, with your PKCE verifier (required of every client) and your client authentication, for an access token and — when openid was granted — an RS256 ID token that says whether this was the person's first sign-in to you.

5. 5

   userinfo

   GET /v1/userinfo returns a flat map of the claim values the person approved and the platform holds.

The discovery document is the contract

Do not hard-code endpoints from a page you read once. GET /.well-known/openid-configuration returns issuer, authorization_endpoint, token_endpoint, userinfo_endpoint and jwks_uri, and your application's quickstart returns the same set under endpoints.

{
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code"],
  "subject_types_supported": ["pairwise"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic", "client_secret_post", "none"
  ],
  "code_challenge_methods_supported": ["S256"],
  "prompt_values_supported": ["none", "login", "consent", "select_account"]
}

The JWKS answers with RSA keys carrying kid, use: "sig" and alg: "RS256". Select by kid, and re-fetch when you meet one you do not know.

Your one sentence

purpose is the only text you write that the person reads at the moment they decide. It is one string, at most 200 characters, stored on the consent record. If you send nothing, the screen says Sign in to <your application name>.

There is no per-claim reason field. You cannot annotate date_of_birth with why you want it on the screen. One request, one sentence.

First sign-in or returning

The first approval creates a connection. Later sign-ins reuse the active consent unless more permissions are requested. With a sufficient session and unchanged permissions, continuation is automatic. Authentication is requested when needed, and each completed sign-in is recorded.

prompt, max_age and login_hint

Three OpenID Connect parameters authorize reads. Anything else you send is forwarded and ignored.

A private sign-in application cannot send max_age, which is refused with invalid_request, and its login_hint is dropped. See Private sign-in.

Subjects are pairwise

subject_types_supported is ["pairwise"]. The sub is derived per client id. Your staging application and your production application see different sub values for the same human being, and so do two products you own.

Key your user records on it anyway — just do not treat it as a UnifyID-wide person id, and do not try to join two applications on it.

A private sign-in application's sub is per client id too, and never equal to a pairwise one. It belongs to the person rather than to their UnifyID account: in production it stays the same after they delete their account and register again with the same identity document, where a standard application's sub would be new. See Private sign-in.