Skip to Content
Web SDKGetting startedPrerequisites

Prerequisites

Confirm each of these before you start the Getting started flow.

Browser

A modern browser with getUserMedia and WebAssembly:

  • Chrome 91 or newer
  • Firefox 89 or newer
  • Safari 16.4 or newer
  • Edge 91 or newer

See Browser support matrix for per-feature coverage.

HTTPS

Camera access through getUserMedia is blocked on plain HTTP origins. You need one of:

  • HTTPS in production.
  • http://localhost or http://127.0.0.1 for local development.

A token provider

The SDK authenticates every backend call with a Keycloak bearer token in the Authorization: Bearer header. The SDK never holds a secret: your backend mints a short-lived token, and the SDK consumes it through the auth.tokenProvider.getToken() callback, re-requesting a fresh one whenever the backend returns a 401.

You need a backend endpoint that mints these tokens for your integration. See Authentication for how to set up the token broker and wire it to getToken().

Private registry access

@sladeid/slade-id-sdk is published to a private registry, https://npmjs.slade360.co.ke/. You need a read token for it, issued by your Slade ID contact.

There are two separate pieces of configuration, and keeping them separate is the whole trick:

Belongs inCommitted?
Scope mapping — which registry serves @sladeidproject .npmrcyes, it holds no secret
Credential — the token for that registryuser-level confignever

1. Scope mapping — in the repository

Create a .npmrc next to your package.json containing exactly one line, and commit it:

@sladeid:registry=https://npmjs.slade360.co.ke/

Only the @sladeid scope is redirected. Every other dependency keeps resolving from the public registry, which is why this is safe to commit and safe to share.

(npm config set @sladeid:registry=https://npmjs.slade360.co.ke/ --location=project writes the same line. Without --location=project it lands in your user config instead, which works locally but leaves nothing in the repo for your colleagues or CI.)

2. Credential — on the machine, once

# pnpm
pnpm config set "//npmjs.slade360.co.ke/:_authToken" <your-token>
 
# npm
npm config set "//npmjs.slade360.co.ke/:_authToken" <your-token>

Both write outside the repository: npm to ~/.npmrc, pnpm to its own auth file (~/Library/Preferences/pnpm/auth.ini on macOS, under $XDG_CONFIG_HOME/pnpm elsewhere). Nothing to gitignore, nothing to leak in a diff.

In CI, run the same command as a job step and read the token from a masked variable:

before_script:
  - pnpm config set "//npmjs.slade360.co.ke/:_authToken" "$SLADEID_TOKEN"

Then install normally — no --registry flag needed, because the scope mapping already points @sladeid at the right host:

pnpm add @sladeid/slade-id-sdk
npm install @sladeid/slade-id-sdk

Do not put the token in the project .npmrc

Not the literal token, and not an environment-variable reference either:

# ✗ This is broken. pnpm will not authenticate.
@sladeid:registry=https://npmjs.slade360.co.ke/
//npmjs.slade360.co.ke/:_authToken=${SLADEID_TOKEN}

pnpm deliberately refuses to expand environment variables in registry credentials that come from a project .npmrc. That file is committed, so a tampered registry line in a pull request could ship your token to a host you do not control. pnpm skips the line with a warning and carries on unauthenticated:

[WARN] Ignored project-level auth setting "//npmjs.slade360.co.ke/:_authToken" in ".npmrc":
environment variables are not expanded in registry credentials that come from a project .npmrc,
because that file is committed to the repository and could leak the secret to an
attacker-controlled registry.

[ERR_PNPM_FETCH_401] GET https://npmjs.slade360.co.ke/@sladeid%2Fslade-id-sdk: Unauthorized - 401
No authorization header was set for the request.

Two reasons this form keeps getting reinstated, and why you should not:

  • npm expands it. Under npm the same file works, so a project that only ever tested with npm looks fine until the first pnpm user runs a clean install.
  • A warm store hides it. pnpm serves the tarball from its content-addressable store without contacting the registry, so a machine that has installed the package before never authenticates and never fails. The break only shows up on a genuinely clean machine — a new laptop, a fresh CI runner, a Windows box with an empty store.

Move the credential to user-level config (step 2) and the project file back to the scope mapping alone.

always-auth does nothing

If you inherited an .npmrc with always-auth=true, delete the line. npm stopped using the setting years ago and spent a major version reporting it as an unknown config; pnpm never needed it and authenticates against a private registry without it. It is noise that looks like configuration.

A <video> element

The capture sessions attach to an HTMLVideoElement you provide. The element must be in the DOM before you call session.start(). The element does not need to be visible — for headless capture flows you can position it off-screen — but it must exist.

Next stepsOverview