Concepts

Identity

A person's account. It has a permanent identifier — sub — and that is what arrives in the token. Store it on your side as the user key.

One identity holds several email addresses, passkeys, backup codes and links to Google or Entra. All of these are ways into the same account, not different users.

Client

Your site or application as auth.my sees it. A client has a client_id, a secret (if it runs on a server) and a list of redirect URIs.

A client is either confidential — code runs on your server and the secret never leaves it — or public: a single-page app or mobile client, where there is nowhere to hide a secret. Public clients have no secret; their security rests on PKCE and exact redirect URI matching.

Redirect URI

Where we send the authorization code after sign-in. The match is checked character by character: scheme, host, port, path, trailing slash.

This strictness is not pedantry. A relaxed check means an authorization code can be redirected to somebody else's address, and the account with it.

You do not have to assemble the URI by hand: when registering a client, enter your site address and pick your library, and the path is filled in for you.

Grant

The user's consent for your site to receive particular data. Issued once per set of scopes. Ask for a new scope and consent is requested again.

Users can revoke a grant in their console. Issued tokens then stop working.

Organization

A company that owns one or more domains. An address in a verified company domain creates an account the organization controls rather than the person: it can remove a member and take access away.

See Domains and Members.

Tokens

Token	Purpose
id_token	a signed statement that this person signed in
access_token	the key to /me — fresh profile data
refresh_token	extends access without signing in again

Lifetimes and refresh rules are in Tokens.