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 EntryIdP compares the result against their enrolled biometric.

What happens if the liveness check fails?

EntryIdP returns the user to the relying party with an access_denied error. There is no fallback credential method by design, so a failed liveness check issues no session.

What happens if a user can no longer sign in, for example after a significant change in appearance?

This is rare in practice. The face template tolerates ordinary change in appearance over time, and a user whose scan does not resolve can simply retry.

For 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 recovery is never a weaker path than enrolment, and it adds support-assisted review for exceptional cases. We are deliberately building recovery after identity verification rather than before it, so 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 you need nothing special to switch it 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: no cached session exists, so nothing can satisfy the check from cache.

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 you do not need to send them. If your library adds them automatically, they cause no problem.

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. There is no support ticket, no release, and no dependency on the platform team. The default is a confidence score of 90. EntryIdP enforces a floor of 70 server-side, so no tenant can configure the control below a safe level.

You configure the type of liveness challenge presented to users 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 designed to reject flat images, screen replays, and masks. iBeta — an independent, NIST/NVLAP-accredited laboratory — has tested it against ISO/IEC 30107-3, the international standard for presentation-attack detection. It passed both Level 1 and Level 2 at a 0% attack-acceptance rate: the test set contained no presentation attack that 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. AWS holds that certification for the liveness model itself.

EntryIdP adds its own controls on top, because presentation-attack testing addresses what someone holds up in front of a camera rather than what software may attempt at the application layer:

• EntryIdP never trusts the browser's report of the result. It independently re-verifies every session server-side against the liveness service before issuing any token.
• EntryIdP enforces the confidence threshold server-side, not client-side.
• EntryIdP enrols the image the liveness session produced, never an image the client supplied.

The combination is a certified detector plus an architecture that treats the client as untrusted throughout.

How does identity verification relate to the face check?

They are two independent layers. The separation is deliberate, and worth understanding when you plan 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. This layer includes 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 backs the verified-identity claim EntryIdP releases to relying parties. Because it is a separate layer, the strength of the biometric controls above never depends on it, and you can shape how identity verification is applied to each tenant's risk model.

Provider coverage is per country and per tenant by design, so we add markets without changing the authentication path. Decision 011 covers current and planned registry coverage for a specific market. Ask us for the position on the markets you are launching in.

---

Integration for relying parties

What OAuth2/OIDC flows are supported?

Authorization Code + PKCE only. This is the only flow enabled:

• response_type=code
• code_challenge_method=S256 (required — PKCE is mandatory for all public clients)

EntryIdP does not support Client Credentials, Implicit, or Resource Owner Password grants, and will never add them.

Where is the discovery document?

GET /.well-known/openid-configuration

This 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.json

The JWKS contains the current RS256 public key. Cache it, and re-fetch it when you encounter an 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 verification 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. EntryIdP returns all PII from the UserInfo endpoint, not in the ID token.

EntryIdP advertises liveness:result and roles in discovery, but they don't gate anything: the claims they describe are always present in the ID token, whatever 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. Register redirect URIs per client in advance; EntryIdP matches them 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. EntryIdP shares the face index 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: EntryIdP refuses a face already enrolled anywhere in the ecosystem. Your application makes no call, and there is 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, we can scope that deliberately between them. Talk to us about the use case.

How does our backend confirm a token is still valid?

Use two mechanisms 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 your client_id, plus client_secret if 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 your 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 and assign roles within the tenant;
• review their own audit trail;
• 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 you can exercise features that depend on identity verification end-to-end. They also provide 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. We size the limits against one person doing one thing at a time, so load tests, validation cohorts, and abuse are what encounter them. That is the intent.

Two 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.

Design around the application layer, which applies 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, because 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.

When you exceed an application limit, EntryIdP 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, so 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 scopes
• tenant_id — the tenant the user belongs to; absent if they aren't enrolled in the client's tenant
• roles — 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?

No. Each refresh token is single-use and rotated on every use. If anyone presents a previously used refresh token — a replay attempt — EntryIdP immediately revokes the entire token family, and the user must re-authenticate with liveness.

---

Data and privacy

What biometric data is stored?

EntryIdP stores a face template in AWS Rekognition: a mathematical vector embedding, from which no one can reconstruct the original image. Where a deployment enables enrolment-image retention, EntryIdP holds the enrolment selfie in encrypted S3 storage, accessible only to authorised administrators, and uses it solely for disaster recovery of the face index. EntryIdP deletes the ID-document images as soon as identity verification completes, because they have no purpose beyond that point. No API ever returns biometric data.

Where is data stored?

EntryIdP stores account records, verified identity data, and audit history in AWS eu-west-2 (London). Face templates and liveness processing run in AWS eu-west-1 (Ireland).

AWS offers Rekognition Face Liveness in a subset of its regions rather than all of them, and eu-west-1 is the region EntryIdP uses. It is adjacent to the eu-west-2 primary deployment, so all processing stays within the EU/UK data-protection perimeter. We can confirm regional availability for a specific deployment on request.

How do I request deletion of my data?

You 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 your behalf.

EntryIdP handles the face template slightly differently, and deliberately so. On deletion, it immediately and permanently bars the account from authenticating: it records the subject on a block list that it checks before any sign-in can proceed, so a retained template can never resolve a session again. It then holds the template itself for a defined retention period as a fraud-prevention control, which stops a bad actor from deleting an account purely to shed history and re-enrol as a new person. EntryIdP purges the template 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. We built EntryIdP around that from the outset rather than retrofitting 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 images once verification completes;
• self-service data export for subject-access requests;
• 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 we are completing it with legal review ahead of production launch. We can provide current status, the data-processing agreement, and sub-processor details to prospective and existing tenants on request.

---

Security

How are tokens signed?

EntryIdP signs all JWTs 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. EntryIdP publishes the corresponding public key at /.well-known/jwks.json.

What happens if EntryIdP's signing key is compromised?

No one can extract the signing key, because AWS KMS holds it. The realistic threat model is IAM credential abuse rather than key extraction, which AWS CloudTrail makes detectable and which you stop immediately by revoking the credential. In every scenario, recovery is a single key rotation: all tokens signed with the old key immediately fail validation across all relying parties. We can provide the detailed threat analysis 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 unconditional.

Your application can still keep users signed in. Session persistence belongs to the relying party, and the refresh token is the mechanism:

1. Request the offline_access scope to receive a refresh token (30 days, rotated on every use).
2. Store it, and exchange it for a new access token when your app starts or when the current one expires.

EntryIdP does not ask the user to scan again. They return to the liveness check only when the refresh token expires, when someone revokes it, or when you deliberately send them back through authorization for a step-up.

So a user 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.

Plan for two points:

• 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, so no one can trade a compromise in one integration 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 anyone compromises the page; 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.