The standard flow (OIDC): UIID authentication is built on OpenID Connect. To start a login, redirect the user to GET /oauth/authorize with your client_id, redirect_uri, response_type=code and the scopes you need (for example openid profile email alias:read:public). After the user authenticates, they're sent back to your redirect_uri with a code.
Exchanging the code for a token: POST /oauth/token with grant_type=authorization_code, the code, your client_id and client_secret, and the same redirect_uri returns a bearer_token — specifically an access_token, a token_type of Bearer, an expires_in value (typically 3600 seconds), a refresh_token, and the granted scope.
Refreshing an expired token: Access tokens are short-lived by design. Call POST /oauth/token again with grant_type=refresh_token and your refresh_token to get a new access token without asking the user to log in again.
Reading the user's claims: GET /oauth/userinfo with an Authorization: Bearer header returns the authenticated user's claims, including sub (their DID, e.g. did:uiid:9D1B-3239-5D1D-8399), name, email, email_verified, and uiid_core_id.
Auto-configuring your client: GET /.well-known/openid-configuration and GET /.well-known/jwks.json let standard OIDC libraries (such as NextAuth or Passport) configure themselves automatically and verify ID token signatures, without you hard-coding every endpoint.
Registering your application: Before any of this works, onboard your app with POST /api/v1/applications (name and redirect_uri), which returns your client_id and client_secret. Access can be revoked at any time with DELETE /api/v1/applications/{id}.
Enterprise SSO — bridging into SAML, LDAP and Active Directory: UIID is compatible with Keycloak Identity Brokering, so it can be positioned as your organization's "Master IdP" and bridged into legacy SAML 2.0 environments, LDAP, or Active Directory — with zero-code enterprise integration, SAML 2.0 bridge support, B2B multitenancy through Realms, and isolation between different corporate identities.
Recognizing returning visitors without a redirect ("Smart Tags"): GET /api/v1/auth/check, called with credentials: 'include' so it can read the HttpOnly session cookie, tells you silently whether a visitor is already logged in (logged_in: true/false plus their uiid) — without interrupting them with a redirect. If they're not logged in yet, you can generate a temporary UIID via /api/v1/core/uiid/generate, store it locally, and later let the visitor "claim" it through the registration flow — carrying over any local data they built up as an anonymous visitor.