Sign in with Unidy.

1. 1

   Register your website

   In the Unidy app, your company's approved Unidy business account opens Developers and adds a website: its name, web address, privacy policy and, if you like, a logo. Then the details (scopes) the website may ask for. A request for any other scope is refused.

   Choose once how it signs people in:

   • With a server: you get a client id and a secret, shown once. The server exchanges the code.
   • In the browser: a client id and no secret. PKCE with S256 is required, and only your redirect origins may call the token endpoint.
   • Redirect addresses: up to 10, all https on one host. For your own machine, register a second website with http://localhost addresses.
2. 2

   Read the discovery document

   Read the endpoints from it rather than hard-coding them.

   curl https://id.unidy.com/.well-known/openid-configuration
   
   {
     "authorization_endpoint": "https://id.unidy.com/oauth2/auth",
     "token_endpoint": "https://id.unidy.com/oauth2/token",
     "userinfo_endpoint": "https://id.unidy.com/userinfo",
     "jwks_uri": "https://id.unidy.com/.well-known/jwks.json",
     …
   }

3. 3

   Send the authorization request

   Make a random verifier and keep it, with a random state and nonce, until the person comes back. Send the SHA-256 challenge of the verifier.

   const base64url = (bytes) =>
     btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
   const random = () => base64url(crypto.getRandomValues(new Uint8Array(32)));
   
   const config = await (await fetch('https://id.unidy.com/.well-known/openid-configuration')).json();
   const verifier = random(), state = random(), nonce = random();
   const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
   
   const url = new URL(config.authorization_endpoint);
   url.search = new URLSearchParams({
     response_type: 'code',
     client_id: 'YOUR_CLIENT_ID',
     redirect_uri: 'https://shop.example/callback',
     scope: 'openid profile unidy_id email',
     state,
     nonce,
     code_challenge: base64url(new Uint8Array(digest)),
     code_challenge_method: 'S256',
   });
   location.assign(url); // keep verifier, state and nonce in sessionStorage first

4. 4

   Exchange the code for tokens

   On your redirect page, check that state matches the one you sent, once. Then exchange the code. A server authenticates with its secret (HTTP Basic). A browser website sends client_id instead, with no secret.

   curl -X POST https://id.unidy.com/oauth2/token \
     -u 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \
     -d grant_type=authorization_code \
     -d code=THE_CODE \
     -d redirect_uri=https://shop.example/callback \
     -d code_verifier=THE_VERIFIER
   
   { "access_token": "…", "id_token": "…", "token_type": "bearer", "expires_in": …, "scope": "openid profile unidy_id email" }

5. 5

   Validate the ID token

   Never trust an ID token you haven't checked. Your OpenID Connect library does all of this:

   • The signature, with the key from jwks_uri that matches the token's kid.
   • iss equals the issuer in the discovery document.
   • aud contains your client id.
   • exp is still in the future.
   • nonce equals the one you sent.
6. 6

   Identify the person

   Key the account by sub. It's private to your website: the same person has a different sub everywhere else, so nobody can follow them across the web with it.

   Use unidy_id to show who signed in. It's the Unidy ID the person goes by, and they can personalise it, so it isn't a key.

   {
     "sub": "8b1c2f…e40f",
     "aud": ["YOUR_CLIENT_ID"],
     "nonce": "…",
     "name": "Ana Ruiz",
     "unidy_id": "ana.ruiz",
     "email": "ana.shop@mail.example",
     "email_verified": false
   }

7. 7

   Create your own session

   Look sub up in your records. Unidy never tells you whether the person is new: if you have no account for that sub, create one. Then start your usual session.

8. 8

   Optional: read the details with the access token

   GET /api/v1/me answers sub and each detail the person agreed to share and still allows. After Allow once, or if the person disconnects your website, it answers not_linked.

   curl https://id.unidy.com/api/v1/me \
     -H 'Authorization: Bearer ACCESS_TOKEN'
   
   { "sub": "8b1c2f…e40f", "name": "Ana Ruiz", "email": "ana.shop@mail.example", "email_verified": false }

API

Unidy.init({ clientId, redirectUri, scopes, issuer, storage })

Sets the SDK up. Call it on every page first.

Unidy.button(element, { kind, theme, lang })

Draws the official Continue with Unidy button.

Unidy.signIn({ scopes, prompt })

Sends the person to Unidy with PKCE (S256), a state and a nonce.

Unidy.handleRedirect()

Checks the state, exchanges the code, validates the ID token and resolves to { user, kind, scopes }.

Unidy.user()

The signed-in person's claims, or null.

Unidy.details()

The details the person agreed to, from /api/v1/me.

Unidy.signOut()

Forgets the tokens and revokes the refresh token at Unidy.

Unidy.UnidyError

Every failure, with a code such as access_denied, not_linked or invalid_token.