Persona identity verification

Prerequisite: an account option opened by Beedeez, without which neither the Persona row nor the activation condition appears. Plus a Persona contract, an API key and at least one inquiry template created on the vendor side.

Permissions needed: access to the account configuration, and to the capsule editor.

What it is for

Persona is an external identity-verification vendor, and the word means nothing else here. On a capsule whose activation condition is After identity check (Persona), a learner cannot start the content without a valid verification. It is set capsule by capsule.

Where it is set

On the account: Configuration › Integrations › External Services, the Persona row, then the Persona Configuration button. Six fields:

• API key and Webhook secret, masked once saved.
• Inquiry template ID (itmpl…): the Persona form played on the first verification.
• Renewal inquiry template ID (itmpl…): an alternative form for a learner who has already completed a verification. See below for the exact condition under which it is used.
• Webhook header name: persona-signature by default.
• Verification TTL (minutes): how long an approved verification stays valid. When this field is empty, Beedeez falls back to 24 hours.

The Inquiry template ID must start with itmpl. If it does not, no learner can start the verification and every capsule carrying the condition stays locked.

On the capsule: the Diffusion tab, Custom visibility and activation conditions, then the activation condition After identity check (Persona). Two settings appear: Enable capsule-specific verification validity and Verification validity duration (minutes), with a floor of 5 minutes.

How far one verification goes

This is the setting to get right, because it decides whether a learner verifies once or repeatedly.

Enable capsule-specific verification validity is off by default. In that state, an approved verification is not attached to any capsule: it covers every capsule on the account carrying the After identity check (Persona) condition, for the duration of Verification TTL (minutes).

Turn Enable capsule-specific verification validity on for a capsule, and its verification is tied to that capsule alone. The learner must verify again for it even if another verification is still valid elsewhere, and Verification validity duration (minutes) replaces the account TTL for that capsule.

💡 Enable it on the few capsules that need a check of their own, such as an exam. Leaving it off everywhere else spares learners a repeated verification.

Which form the learner is shown

The Renewal inquiry template ID is used only when both conditions hold: the learner has already completed an approved verification in the scope that applies, and a renewal ID starting with itmpl is saved. If either is missing, the Inquiry template ID form is played again.

The scope that applies is the one described above, so a learner who is treated as returning on one capsule can still be treated as new on a capsule with its own validity.

What the learner goes through

On the capsule card, a badge reading Identity verification required. On the start page, a locked box with the same title: “You must complete an identity check before starting this capsule.” The action button becomes Verify identity.

Pressing it creates an inquiry at Persona and opens the vendor-hosted flow: full screen inside the app on mobile, in a pop-up in a browser, falling back to a full-page redirect if the pop-up is blocked. What the learner is asked for there is defined by the inquiry template, not by Beedeez.

While the flow is open in a browser, the app asks Beedeez every 3 seconds whether the verification has been approved, and starts the capsule as soon as it is. The start page then shows Identity verified until followed by the expiry date. If the inquiry cannot be created: “Identity verification cannot be started right now. Please try again later.”

Validity is read when the start page loads, and checked again when the capsule opens. If it has expired by then, or if that check cannot reach Beedeez, the capsule closes and the learner is returned to the start page.

What Persona sends back

Persona calls Beedeez on POST /api/v1/webhooks/persona. The call is authenticated: an HMAC-SHA256 signature computed over the timestamp and the raw body, carried in the configured header in the t=…,v1=… format, with a 5-minute tolerance. With no Webhook secret saved, the call is rejected with a 401. Only inquiry.* events are processed.

The learner is matched through metadata.ownerId and metadata.userId, or failing that through reference-id, shaped as ownerId:userId. The status is reduced to three values: approved (from approved, completed, passed, completed-success), declined (from declined, failed, completed-failure), and pending for anything else. An already approved verification is never downgraded.

What Beedeez keeps

⚠️ No identity document, no photo, no name and no date of birth pass through Beedeez. The document stays with Persona, and its retention is a matter for your contract with them.

Per verification, Beedeez records: the inquiry identifier and that of the template used, the status reduced to the three values above, the verification, expiry and last-webhook dates, a flag saying a first verification was completed, and an audit summary of the event (name, inquiry identifier, raw status, reception date, account and learner identifiers).

What it does not do

• No back-office screen shows a learner’s verification status. No list, no user record, no export.
• No manual approval. An administrator can neither approve nor unblock a learner: someone who keeps failing has no recourse inside the product.
• No attempt limit. Every retry creates a new inquiry at Persona.
• These records escape both the personal-data export and the anonymisation of a learner account. Flag this to your DPO.
• The check does not apply in preview, in review, or when the capsule is opened inside a session.

Going further

• Capsule visibility and activation conditions: where the activation condition is chosen, and the other conditions available.
• Configuring a webhook endpoint: how Beedeez webhooks work in general, to place this one.
• Setting up security, GDPR and legal information: the framework to settle with your DPO before first use.