# byLegit

> byLegit is an ethical website and company review platform. It is also an OAuth 2.1 /
> OpenID Connect identity provider: any third-party site can offer "Sign in with byLegit".

Human documentation: https://bylegit.com/developers

## Fastest integration: hosted drop-in script (no popup, no backend)

    <script src="https://bylegit.com/bylegit.js"></script>
    <script>
      const bylegit = byLegit.create({ scope: "openid email profile",
                                       redirect_uri: window.location.origin + "/login" });
      bylegit.handleRedirect().then((user) => { if (user) console.log(user); });
      document.querySelector("#bylegit-signin").onclick = () => bylegit.signIn();
    </script>

The script reads discovery, self-registers the client, stores the client_id locally
and performs a FULL-PAGE REDIRECT with PKCE (S256). Never open a popup or a new
window for byLegit sign-in: popup blockers break it and it is not required.
`handleRedirect()` returns null on a normal page load, or
{ sub, email, name, picture, claims, tokens } after byLegit redirects back.
Forward `tokens.id_token` to your backend if you need server-side verification.

## Sign in with byLegit — integration contract

- Protocol: OAuth 2.1 authorization code flow with PKCE (S256). OpenID Connect ID tokens.
- Discovery document (single source of truth for all endpoints):
  https://bylegit.com/.well-known/oauth-authorization-server
  It returns issuer, authorization_endpoint, token_endpoint, jwks_uri and
  registration_endpoint. Never hardcode endpoints; read them from discovery.
- Client registration: dynamic client registration is enabled at the
  registration_endpoint from discovery. Register the exact HTTPS redirect_uri
  (byte-for-byte match, including trailing slash).
- Authorization request parameters: response_type=code, client_id, redirect_uri,
  scope, state, code_challenge, code_challenge_method=S256.
- Token request: POST to token_endpoint with grant_type=authorization_code, code,
  redirect_uri, client_id, code_verifier.
- Token verification: verify the ID token signature against jwks_uri and check that
  `iss` equals the `issuer` value from the discovery document, and `aud` equals client_id.

## Scopes and the data the user shares

- `openid` (required): stable account identifier (`sub`).
- `email`: account email address and its verified status.
- `profile`: public display name and profile photo URL.

Request the minimum set. The user sees a byLegit consent screen naming the client
application, the redirect URI, and each requested item before anything is shared.

## Never available through OAuth

- Passwords, session cookies, refresh tokens of the byLegit session.
- Private privacy settings, data-export or account-deletion requests.
- Unpublished draft reviews.
- Business dashboard data of companies the user manages.

## Integrator rules

- HTTPS redirect URIs only; always use PKCE and `state`.
- Never collect byLegit credentials yourself; only the hosted authorization page does.
- Keep tokens server-side; never put them in URLs, analytics or browser logs.
- Use the data only for the consented purpose; delete it when the user disconnects.
- Do not present byLegit reviews as an endorsement of your product.

## Legal

- Terms of use: https://bylegit.com/conditions-utilisation
- Privacy policy: https://bylegit.com/politique-confidentialite
- Legal notice: https://bylegit.com/mentions-legales
- Contact: hello@bylegit.com

# byLegit Business API (customer verification)

Purpose: let a site prove that a reviewer is one of its real customers, without
sharing any personal data in either direction. Keys are created per site in the
byLegit Business console (site page > API tab) and start with `blg_`.
Full docs: https://bylegit.com/api-docs

## Check a key

GET https://bylegit.com/api/public/v1/ping
Authorization: Bearer blg_xxx
-> { "status": "ok", "domain": "example.com", "verify_url_configured": true }

## Mode 1 - push a signup signal

POST https://bylegit.com/api/public/v1/customers
Authorization: Bearer blg_xxx
Content-Type: application/json
{ "email": "person@example.com" }
-> 202 { "status": "accepted" }

The response is always the same; byLegit never discloses whether a byLegit
account exists. Emails are stored only as a keyed hash scoped to the site.

## Mode 2 - answer a lookup

Configure an HTTPS endpoint on the key. byLegit calls it when a review is being
written:

POST <your endpoint>
x-bylegit-signature: HMAC-SHA256(raw body, your api key)
{ "email": "person@example.com" }
-> { "registered": true }

Verify the signature with a timing-safe compare before answering, respond within
6 seconds, and return nothing besides `registered`.

## Verified customer badge

When a signal exists, the reviewer is explicitly asked whether to display the
"Verified customer" badge. Users can disable API verification entirely, or erase
all resulting verification data, in their privacy settings.