Appearance
Frequently asked questions
Common questions from relying parties, integrators, and end users. For endpoint specs, scopes and claims see the Reference; for step-by-step integration see Integrate your app.
Authentication
How does EntryIdP authenticate users?
EntryIdP is biometric-only. There are no passwords, OTPs, magic links, or SMS codes. Every sign-in requires a real-time face liveness check — the user performs a short guided action in front of their camera, and the result is compared against their enrolled biometric.
What happens if the liveness check fails?
The user is returned to the relying party with an access_denied error. There is no fallback credential method by design — liveness failure means no session is issued.
What happens if a user loses access (e.g. changes their appearance significantly)?
In practice this is rare — the face template tolerates ordinary change in appearance over time, and a member whose scan does not resolve can simply retry.
For the cases that need more than a retry, a full account recovery flow is a priority development item, currently in design under Decision 001. The design re-gates re-enrolment behind identity verification (a government-issued ID check) so that recovery is never a weaker path than enrolment, with support-assisted review for exceptional cases. Recovery is deliberately being built after identity proofing rather than before it, so that the recovery gate is as strong as the front door.
Can we require a fresh face check before a sensitive action, such as a withdrawal or an age-restricted purchase?
Yes, and it requires nothing special to switch on. EntryIdP holds no session of its own, so every authorization request triggers a fresh liveness check. Sending a user back through authorization before a sensitive action is therefore a genuine step-up: it cannot be satisfied from a cached session, because no cached session exists.
OIDC defines max_age and prompt=login for asking an identity provider to re-authenticate a user. EntryIdP's default behaviour already exceeds what either parameter asks for, so no parameter is needed to obtain it — and sending them causes no problem if your library adds them automatically.
Who sets the liveness confidence threshold, and how quickly can it change?
Each tenant sets its own threshold, and can change it at any time from the tenant console with immediate effect — no support ticket, no release, no dependency on the platform team. The default is a confidence score of 90, with a floor of 70 enforced server-side so the control cannot be configured below a safe level.
The type of liveness challenge presented to users is configurable per tenant in the same place.
Is the liveness check vulnerable to photos or video replay?
The underlying liveness service is AWS Rekognition Face Liveness, which uses active-challenge techniques specifically designed to reject flat images, screen replays, and masks. It has been tested by iBeta — an independent, NIST/NVLAP-accredited laboratory — against ISO/IEC 30107-3, the international standard for presentation-attack detection, and passed both Level 1 and Level 2 at a 0% attack-acceptance rate: no presentation attack in the test set was accepted, while genuine users still were. Level 1 covers printed photographs and screen replays; Level 2 covers higher-effort artefacts such as custom silicone masks. That certification is held by AWS for the liveness model itself.
EntryIdP then adds its own controls on top, because presentation-attack testing addresses what is held up in front of a camera rather than what software may attempt at the application layer:
- The browser's report of the result is never trusted. Every session is independently re-verified server-side against the liveness service before any token is issued.
- The confidence threshold is enforced server-side, not client-side.
- The image enrolled is the one the liveness session produced — never an image supplied by the client.
The combination is a certified detector plus an architecture in which the client is treated as untrusted throughout.
How does identity verification relate to the face check?
They are two independent layers, which is deliberate and worth understanding when planning an integration.
The biometric layer covers face sign-in, liveness, and one-person-one-account enforcement. It operates entirely on its own and depends on no external party. Included in this layer is a biometric comparison between the live face from the liveness session and the photograph on the submitted identity document, performed at enrolment against a configurable similarity threshold.
The identity-verification layer confirms the declared identity against an authoritative registry, and is what backs the verified-identity claim released to relying parties. Because it is a separate layer, the strength of the biometric controls above never depends on it, and how identity verification is applied can be shaped to each tenant's risk model.
Provider coverage is per country and per tenant by design, so additional markets are added without change to the authentication path. Current and planned registry coverage for a specific market is covered under Decision 011 — ask us for the position on the markets you are launching in.
Integration (Relying Parties)
What OAuth2/OIDC flows are supported?
Authorization Code + PKCE only. This is the only flow enabled:
response_type=codecode_challenge_method=S256(required — PKCE is mandatory for all public clients)
Client Credentials, Implicit, and Resource Owner Password grants are not supported and will never be added.
Where is the discovery document?
GET /.well-known/openid-configurationThis returns the standard OIDC discovery metadata including issuer, authorization endpoint, token endpoint, JWKS URI, and supported scopes.
How do I get a JWKS to validate tokens?
GET /.well-known/jwks.jsonThe JWKS contains the current RS256 public key. Relying parties should cache this and re-fetch on unknown kid. See the Reference for the full endpoint specification.
What scopes are available?
| Scope | Purpose |
|---|---|
openid | Required — issues an ID token |
profile | Name, email address and phone number (self-declared) |
offline_access | Issues a refresh token |
identity:verified | Verified identity, date of birth and ID number (from the identity-proofing bureau) |
liveness:result | Reserved — has no effect today |
roles | Reserved — has no effect today |
There is no email scope — an email address comes with profile. All PII is returned from the UserInfo endpoint, not in the ID token.
liveness:result and roles are advertised in discovery but don't gate anything: the claims they describe are always present in the ID token regardless of what you request. The Reference is the source of truth for scopes and claims.
What redirect URI formats are accepted?
Exact match only. No wildcards, no prefix matching. Redirect URIs must be pre-registered per client and match character-for-character on every authorization request.
Is one-person-one-account enforced, and is the face index shared across the Entry ecosystem?
Yes to both. The face index is shared across the Entry ecosystem — Entry, SecureUs and Gain For Me — so one-person-one-account holds across the whole ecosystem rather than only within a single tenant. Enforcement is automatic at enrolment: a face already enrolled anywhere in the ecosystem is refused, with no call for the integrating application to make and nothing to opt into.
The refusal confirms that the face is already enrolled. It does not disclose which account or identifier it belongs to, which protects every tenant in the index equally — no participant can establish that a given person holds an account under another participant's brand. Where two tenants have a mutual interest in a stronger shared signal, that can be scoped deliberately between them; talk to us about the use case.
How does our backend confirm a token is still valid?
Two mechanisms, used together:
- Local validation. Access and ID tokens are signed JWTs. Fetch the public key once from the JWKS endpoint, cache it, and validate signature, issuer and expiry locally with no network call per request.
- Introspection.
POST /introspect(RFC 7662) reports whether a specific token is still active. Because it consults the revocation list, it reflects revoked tokens and sessions ended from the self-service portal — which local validation alone cannot see until the token expires. Send yourclient_id(plusclient_secretif your client is confidential): the endpoint answers only for tokens issued to you.
Access tokens are deliberately short-lived (15 minutes), so a change in a user's status surfaces at the next refresh. Richer server-to-server signalling of identity and account changes — so a backend can be notified rather than poll — is on the roadmap under Decision 017, which favours the standards-based approach over bespoke callbacks.
Can we manage our own tenant settings and OIDC clients?
Yes. The tenant console is available now, with its own sign-in and a dedicated tenant-administrator role that is structurally separate from platform administration. A tenant administrator can manage the tenant profile, liveness threshold and challenge type, register and manage their own OIDC clients, view their member list, assign roles within the tenant, review their own audit trail, and block a member within their tenant without affecting that person's standing elsewhere in the ecosystem.
Administrators of more than one tenant can switch between them without repeating the liveness scan.
Tenant creation, signing-key rotation and platform-wide account actions remain with the platform team.
Is there test-environment support for building against EntryIdP?
Yes. Non-production environments provide synthetic verified identities so features that depend on identity verification can be exercised end-to-end, and a test-user reset that clears the account together with its face enrolment so the same test subject can enrol repeatedly. Both are restricted to non-production environments by design and cannot be enabled in production.
Deterministic control of liveness outcomes for automated regression suites is on the near-term list — raise it with us as part of integration planning and we will scope it with your test cycle.
Are there rate limits we need to design around?
Yes, in four layers — but ordinary per-user traffic never reaches any of them. They are sized against one person doing one thing at a time, so they are encountered by load tests, validation cohorts and abuse, which is the intent.
Two of the layers are coarse and volumetric: an API Gateway stage throttle, and an AWS WAF rule that blocks a source IP exceeding a generous per-IP request rate. Neither distinguishes one caller from another.
The layer you should design around is the application one, applied to the routes that cost money or that an attacker would enumerate. Its counters key on the most specific identity available — the authenticated user, else the individual login attempt, else the client, else the IP. That ordering matters: users behind a shared corporate or mobile egress IP get independent buckets rather than colliding on one.
The limits worth knowing when you build:
| Endpoint | Counted per | In practice |
|---|---|---|
/token | Relying party (client_id) | 30 per minute. A backend-for-frontend shares one bucket across all of its users, so plan bulk sign-in runs around it. |
/userinfo | End user (sub) | 60 per minute. Effectively unreachable in normal use. |
/introspect, /revoke | Relying party | Sized for normal backend validation traffic. |
| Enrolment and document capture | IP address | Deliberately tight — a user being enrolled has no identity to count against yet. |
Exceeding an application limit returns 429 Too Many Requests with a Retry-After header giving the seconds until the counter resets, and a JSON body of {"error": "rate_limited"}. Honour Retry-After rather than retrying immediately.
Planning a bulk enrolment or a validation cohort? Tell us before you run it. Enrolment is the limit you will hit first, it counts per IP, and thresholds are configuration rather than code — we can raise them in a test environment for the duration of your run.
Tokens
What tokens does EntryIdP issue?
| Token | Format | Lifetime |
|---|---|---|
| Access token | Signed JWT (RS256) | 15 minutes |
| ID token | Signed JWT (RS256) | Issued once at auth time |
| Refresh token | Opaque (DynamoDB-backed) | 30 days, rotated on use |
What claims are in the access token?
Standard claims (sub, iss, aud, exp, iat, jti) plus:
scope— space-separated granted scopestenant_id— the tenant the user belongs to; absent if they aren't enrolled in the client's tenantroles— the user's coarse roles within that tenant; empty array if none
The biometric claims are not on the access token. face_liveness_verified, acr, amr and liveness_confidence_score live in the ID token, which the frontend holds. Your API receives only the access token and doesn't need them: because client_credentials is disabled, a valid EntryIdP access token already means a real human passed a liveness check.
Access tokens also carry "typ": "at+jwt" rather than a bare "JWT" — see Secure your API for what your validator needs, and the Reference for the full claim list.
Can a refresh token be used more than once?
Each refresh token is single-use and rotated on every use. If a previously-used refresh token is presented (replay attempt), the entire token family is immediately revoked and the user must re-authenticate with liveness.
Data & Privacy
What biometric data is stored?
A face template (a mathematical vector embedding, from which the original image cannot be reconstructed) is stored in AWS Rekognition. Where enrolment-image retention is enabled for a deployment, the enrolment selfie is held in encrypted S3 storage accessible only to authorised administrators, and is used solely for disaster recovery of the face index. The ID-document image is deleted as soon as identity verification completes — it has no purpose beyond that point. No biometric data is ever returned through any API.
Where is data stored?
Account records, verified identity data and audit history are stored in AWS eu-west-2 (London). Face templates and liveness processing run in AWS eu-west-1 (Ireland).
Rekognition Face Liveness is offered in a subset of AWS regions rather than all of them, and eu-west-1 is the region EntryIdP uses — adjacent to the eu-west-2 primary deployment, so all processing stays within the EU/UK data-protection perimeter. Regional availability for a specific deployment can be confirmed on request.
How do I request deletion of my data?
Users can request account deletion at any time from the self-service portal (/me). Deletion is immediate and covers the user record, profile, verified identity data, all active sessions and token history, and any retained enrolment images. Platform administrators can also action a deletion request on a user's behalf.
The face template is handled slightly differently, and deliberately so. On deletion the account is immediately and permanently barred from authenticating — the subject is recorded on a block list that is checked before any sign-in can proceed, so a retained template can never resolve a session again. The template itself is then held for a defined retention period as a fraud-prevention control, which prevents a bad actor from deleting an account purely to shed history and re-enrol as a new person. It is purged at the end of that period.
Completing the scheduled purge stage of this lifecycle, and confirming the retention period alongside the wider retention schedule, is a priority development item tracked under Decision 002.
Is EntryIdP GDPR/POPIA compliant?
Biometric data is special-category personal information under GDPR and UK GDPR, and biometric information under POPIA, so EntryIdP is built around that from the outset rather than retrofitted to it.
Controls in place today include an explicit biometric-processing consent step presented before any face capture and recorded server-side against a consent version, separately from OAuth scope consent; server-side recording of terms and privacy-policy acceptance at enrolment; deletion of the identity-document image once verification completes; self-service data export for subject-access requests; and self-service account deletion with an authentication block applied immediately.
The formal compliance programme — data-protection impact assessment, published privacy notice, final consent wording and the retention schedule — is tracked under Decision 002 and is being completed with legal review ahead of production launch. Current status, the data-processing agreement and sub-processor details are available to prospective and existing tenants on request.
Security
How are tokens signed?
All JWTs are signed with RS256 using a private key stored exclusively in AWS KMS. The private key never leaves the KMS HSM boundary — the application sends data to KMS for signing and receives only the signature. The corresponding public key is published at /jwks.json.
What happens if EntryIdP's signing key is compromised?
The signing key is held in AWS KMS and cannot be extracted. The realistic threat model is IAM credential abuse (not key extraction), which is detectable via AWS CloudTrail and immediately stoppable by revoking the credential. In all scenarios, recovery is a single key rotation — all tokens signed with the old key immediately fail validation across all relying parties. The detailed threat analysis is available to tenants on request.
Does EntryIdP support single sign-on (SSO) sessions?
EntryIdP itself is explicitly stateless — there is no identity-provider session cookie, and every authorization request triggers a fresh liveness check. This is a deliberate security posture: re-authentication is always biometric, never a session replay. It is also what makes the step-up guarantee described under Authentication above unconditional.
Your application can still keep users signed in. Session persistence belongs to the relying party, and the refresh token is the mechanism:
- Request the
offline_accessscope to receive a refresh token (30 days, rotated on every use). - Store it, and exchange it for a new access token when your app starts or when the current one expires.
- The user is not asked to scan again. They only return to the liveness check when the refresh token expires, is revoked, or you deliberately send them back through authorization for a step-up.
So a member who closes your app and returns the next day resumes their session normally — the experience your users expect — while every genuinely new authentication remains biometric.
Two points worth planning for:
- This is a per-application session, not cross-application SSO. Signing in to one relying party does not silently sign a user in to another; each application authenticates independently. That containment is intentional — a compromise in one integration cannot be traded for a session in another.
- Where you store the refresh token matters. For mobile and desktop apps, use the platform's secure storage. For browser applications, holding a long-lived refresh token in the page carries an exposure risk if the page is ever compromised; the hardened pattern is a thin backend that holds the token and issues a secure, HTTP-only session cookie to the browser instead. We are happy to review your approach during integration.