Add Login (OIDC)

This quickstart adds Sign in with SenseCrypt to a web application using the OIDC Authorization Code flow with PKCE. Users authenticate with an on-device face scan on their phone — no passwords, and no biometric data ever reaches your servers or ours.

SenseCrypt is a standard OpenID Connect provider, so if your stack already speaks OIDC this is a conventional integration: redirect to authorize, exchange the code, validate the ID token. The face ceremony happens between the redirect and the callback and is invisible to your code.

Prerequisites

• A SenseCrypt tenant. Each tenant is its own OIDC issuer at https://<your-tenant>.<domain>.
• An OIDC application registered in the admin console, with your app's redirect URI allow-listed.
• Your client_id (plus a client_secret for confidential apps; SPAs use PKCE only).

Register the application first: in the admin console, go to Applications → New OIDC application and set a name, your redirect URI(s), and the client type — Confidential for a server-side app (issues a client_secret) or SPA for a browser/native app (PKCE only, no secret).

The Applications → New OIDC application form: name, redirect URIs, and client type.

Confidential vs SPA at a glance

curl https://<your-tenant>.<domain>/.well-known/openid-configuration

{
  "issuer": "https://<your-tenant>.<domain>",
  "authorization_endpoint": "https://<your-tenant>.<domain>/v1/idp/oidc/authorize",
  "token_endpoint": "https://<your-tenant>.<domain>/v1/idp/oidc/token",
  "userinfo_endpoint": "https://<your-tenant>.<domain>/v1/idp/oidc/userinfo",
  "jwks_uri": "https://<your-tenant>.<domain>/.well-known/jwks.json",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token", "urn:openid:params:grant-type:ciba"],
  "id_token_signing_alg_values_supported": ["ES256"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_post", "client_secret_basic", "client_secret_jwt", "private_key_jwt"],
  "scopes_supported": ["openid", "profile", "email", "offline_access"]
}

GET {authorization_endpoint}
  ?response_type=code
  &client_id={client_id}
  &redirect_uri={your_redirect_uri}
  &scope=openid profile email
  &state={state}
  &nonce={nonce}
  &code_challenge={code_challenge}
  &code_challenge_method=S256

{your_redirect_uri}?error=access_denied&error_description=<reason>&state={state}

curl -X POST {token_endpoint} \
  -d grant_type=authorization_code \
  -d code={code} \
  -d redirect_uri={your_redirect_uri} \
  -d client_id={client_id} \
  -d code_verifier={code_verifier}
  # confidential clients also add: -d client_secret={client_secret}

{
  "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6…",
  "id_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email"
}

{ "error": "invalid_grant", "error_description": "…" }

{
  "iss": "https://<your-tenant>.<domain>",
  "sub": "8f2c…stable-per-tenant-id",
  "aud": "{client_id}",
  "exp": 1735689600,
  "iat": 1735686000,
  "auth_time": 1735686000,
  "nonce": "…",
  "email": "jane@acme.com",
  "name": "Jane Doe",
  "amr": ["face", "mfa", "pop"],
  "acr": "urn:sensecrypt:face-aal3"
}

curl {userinfo_endpoint} -H "Authorization: Bearer {access_token}"

{ "sub": "8f2c…", "name": "Jane Doe", "email": "jane@acme.com", "email_verified": true }

Verify it worked

1. Trigger sign-in and complete the email → QR → face proof on your phone.
2. Confirm your callback received a code (not an error) and that state matched.
3. Confirm the token exchange returned an id_token, and that its signature and iss/aud/exp validate.
4. Sign in a second time — the sub should be identical. A stable sub confirms the token validated and the identity is consistent, which is what you key your user records on.

Troubleshooting

• redirect_uri mismatch / rejected at /authorize. The redirect_uri must be on the application's allow-list and match byte-for-byte (scheme, host, port, path). Add every environment's callback URL.
• PKCE errors / invalid_grant. SenseCrypt is S256-only — never send code_challenge_method=plain. The same code_verifier from step 2 must reach step 3. Don't send a code_verifier if you didn't send a code_challenge (SenseCrypt rejects a stray verifier).
• code already used. The authorization code is single-use. Some browsers speculatively prefetch the callback URL, firing the exchange twice; guard your callback so only the first request exchanges the code.
• invalid_client. Wrong client_id/client_secret, or the wrong client type. Confidential clients must send the secret; SPA clients must send no secret (a blank one is rejected).
• id_token signature or aud failures. Verify against the jwks_uri from discovery and check the token's kid (the JWKS may list a current key plus one in a rotation grace window). Make sure the issuer you validate against equals the token's iss.
• error=access_denied on the callback. Either the user declined/failed the ceremony on their phone (error_description carries the reason, e.g. a face mismatch or timeout), or their email isn't permitted for this application by the group access gate. The latter is an authorization decision, not a bug.

Next steps

• Framework quickstarts — Next.js, React SPA, Node/Express, Python/FastAPI.
• Refresh & logout — Tokens & sessions covers offline_access, refresh-token rotation, and RP-initiated logout.
• Who can sign in — Authorization explains the group access gate.
• Other protocols — SAML SSO, SCIM provisioning, and the full API Reference.