VerifiedKnock · Documentation

Okta setup

Help-desk account recovery with Okta Temporary Access Codes. Okta support is in early access: email [email protected] to turn it on for your organization.

What VerifiedKnock does with Okta

When an employee loses their passkey or security key, two VerifiedKnock approvers approve the recovery: a branch supervisor and an HQ help-desk agent. Each approves with their own FIDO2 security key, from a separate VerifiedKnock account. The same account cannot give both approvals. VerifiedKnock then asks Okta for a short-lived, single-use Temporary Access Code and shows it only on the employee’s own device, the one that opened the recovery link. The employee signs in to Okta with the code and registers a new passkey. Reading the account uses a read-only onboarding app. Issuing the code uses an optional recovery app, which an owner or admin sets up in VerifiedKnock.

The code is never emailed, never shown to the approvers, and never stored or logged by VerifiedKnock.
If the employee’s device does not confirm it received the code within about two minutes, VerifiedKnock revokes the code in Okta.
VerifiedKnock refuses recovery for accounts with a directly assigned Okta administrative role, and for users who are not active.
The help-desk agent can remove the one lost authenticator (security key, passkey or Okta Verify) they select.
Every request, approval, refusal, issued code and revocation is recorded in the VerifiedKnock audit trail.

VerifiedKnock does not change passwords, user profiles, group memberships, app assignments or policies in Okta, and never resets all of a user’s factors. VerifiedKnock does not check ID documents. Your organization decides how supervisors identify employees in person.

Before you start

An Okta Identity Engine org. Classic Engine is not supported.
An Okta super admin for the Okta steps below.
A VerifiedKnock organization with Okta turned on (early access, email [email protected]), and an owner or admin with an enrolled FIDO2 security key.
Your Okta org URL ends in .okta.com, .oktapreview.com or .okta-emea.com, or is a verified Okta custom domain. VerifiedKnock then calls only the canonical Okta address.
Branch supervisors and HQ help-desk agents each have their own FIDO2 security key. Employees do not need one.

Two Okta apps

VerifiedKnock uses the Okta org authorization server and the OAuth 2.0 client credentials flow. Keep onboarding and recovery in two apps. The onboarding app is read-only. The recovery app is optional and is the one that can issue a Temporary Access Code.

	Onboarding app	Recovery app (optional)
Suggested name	VerifiedKnock Help Desk	VerifiedKnock Recovery
Okta API scopes	`okta.users.read`, `okta.roles.read`	`okta.users.manage`, `okta.authenticators.read`
Admin role	Read-only Administrator	Custom admin role, limited to the VK Recovery group

A separate recovery app is recommended. You can instead use the same app for both, and grant the recovery scopes and custom role on the onboarding app. New connections leave recovery off until an owner or admin turns it on. Onboarding can be connected either way.

Onboarding scopes (read-only)

Scope	Okta API calls	Why
`okta.users.read`	`GET /api/v1/users/{login or id}; GET /api/v1/users/{id}/groups; GET /api/v1/users/{id}/authenticator-enrollments`	Find the employee by Okta username, confirm the account is active, list their authenticators, and list their groups for the admin check.
`okta.roles.read`	`GET /api/v1/users/{id}/roles`	Refuse recovery for an account with a directly assigned Okta administrative role.

Recovery scopes

These belong on the recovery app. They are not required for the onboarding connection.

Scope	Okta API calls	Why
`okta.users.manage`	`POST /api/v1/users/{id}/authenticator-enrollments/tac; DELETE /api/v1/users/{id}/authenticator-enrollments/{enrollmentId}`	Create one single-use Temporary Access Code after both approvals. Delete a code the employee did not collect, and remove the one lost authenticator the help-desk agent selects.
`okta.authenticators.read`	`GET /api/v1/authenticators`	Confirm the Temporary Access Code authenticator exists and is active before any recovery action.

Step 1: Temporary Access Code authenticator

Okta Admin Console → Security → Authenticators → Add authenticator → Temporary Access Code:

Minimum lifetime 10 minutes, maximum 60 minutes, default 60 minutes.
Length 12 characters, letters and numbers.
Multi-use: off. VerifiedKnock always asks for a single-use code and cancels the action if Okta returns a multi-use code.
Keep the code lifetime in VerifiedKnock Help desk settings between 10 and 60 minutes.

Step 2: Passkey authenticator the employee will register

Security → Authenticators → Passkeys (FIDO2 WebAuthn) → Edit: set user verification to Required. Block synced passkeys if your policy requires device-bound keys.

Step 3: VK Recovery group and sign-in rule

Directory → Groups → Add group, name it VK Recovery. Add only employees who may need supervised recovery. Do not add administrators.
Add the same rule, at priority 1, to both Security → Authentication Policies → Okta Account Management Policy and App sign-in policies → Okta Dashboard:
- Name: VerifiedKnock recovery. IF user is a member of VK Recovery.
- THEN access is Allowed after successful authentication, with Any 1 factor type.
- Authentication methods: Allow specific authentication methods → Temporary Access Code only.
Do not edit the Catch-all rule in either policy.

Step 4: Create the onboarding app

This app only reads. Choose one way for it to sign in to Okta.

Option A: Okta Integration Network (client secret)

VerifiedKnock is not yet listed in the Okta Integration Network. These steps apply once the listing is published. Until then, use Option B. The listing is the onboarding app. Recovery is Step 6, not part of the install.

Okta Admin Console → Applications and Resources → API Service Integrations → Add Integration. Select VerifiedKnock and click Next.
Review the requested read-only scopes and click Install & Authorize.
Copy the client secret. Okta shows it only once.
Click Done. On the General tab, copy the Okta domain and Client ID.

Option B: Your own API service app (public/private key)

Okta Admin Console → Applications → Create App Integration → API Services. Name it VerifiedKnock Help Desk.
Client authentication: Public key / Private key. You can keep Require Demonstrating Proof of Possession (DPoP) checked; VerifiedKnock sends DPoP proofs.
Copy the Client ID (starts with 0oa).
Okta API Scopes tab → Grant okta.users.read and okta.roles.read only.
After Step 5, paste the public key VerifiedKnock shows into General → Client Credentials → Public keys → Add key.

Onboarding admin role

Okta checks the app’s admin role as well as its scopes. On the onboarding app’s Admin roles tab, assign Read-only Administrator. Scopes alone are not enough for VerifiedKnock to read users and role assignments. Do not grant the recovery scopes on this app if you will use a separate recovery app. Do not turn on Public client app admins. It makes the app a super admin.

Step 5: Connect the onboarding app in VerifiedKnock

Sign in at pass.verifiedknock.com/platform/login with your security key.
Open Help desk settings → Identity provider → Okta.
Choose how VerifiedKnock signs in to Okta: Client secret (Option A) or Public/private key (Option B).
Enter the Okta org URL and the onboarding Client ID, plus the Client secret for Option A.
Tap your security key. A client secret is stored encrypted and is never shown again; the console shows only a mask. For Option B, VerifiedKnock shows the public key to paste into the onboarding app’s Public keys.
Click Run check. VerifiedKnock gets a token and confirms okta.users.read and okta.roles.read. It reads no user data. When those pass, the status is Connected. Recovery can still be off.

With a client secret, VerifiedKnock first requests a token without DPoP. If Okta requires DPoP for the app, VerifiedKnock retries with a DPoP proof. If no token can be obtained, every help-desk action is refused and nothing changes in Okta.

Step 6: Set up recovery

Organization owners and admins only. On the Okta card, open Set up recovery. The recommended choice is a separate recovery app. Same app is available if you want one app to do both. Saving asks for a security-key tap. Recovery is not available until you click Run check and that part passes.

Separate recovery app (recommended)

Okta Admin Console → Applications → Create App Integration → API Services. Name it VerifiedKnock Recovery.
Client authentication: Public key / Private key. Keep Require Demonstrating Proof of Possession (DPoP) checked.
Copy the Client ID. It must be different from the onboarding app.
Okta API Scopes → Grant okta.users.manage and okta.authenticators.read.
Admin roles → create a custom admin role limited to a resource set that contains only the VK Recovery group. Include these permissions:
- View users and their authenticator enrollments.
- Manage Temporary Access Codes (okta.users.credentials.manageTemporaryAccessCode).
- Reset or remove authenticators (okta.users.credentials.resetFactors).
Do not turn on Public client app admins.
In VerifiedKnock, choose Separate recovery app, enter that Client ID, and click Save recovery setup. Tap your security key.
VerifiedKnock shows the recovery app’s public key, with a Copy button. Paste it into that app’s General → Client Credentials → Public keys → Add key. Saving again creates a new key; paste the new one and remove the old one in Okta.
Click Run check.

Same app

Choose Same app as onboarding and click Save recovery setup. Tap your security key. No new public key is created. On the onboarding app, also grant okta.users.manage and okta.authenticators.read, and assign the custom admin role above in addition to Read-only Administrator. Then click Run check.

Turn recovery off

Click Turn recovery off, confirm, and tap your security key. VerifiedKnock deletes the stored recovery key. The onboarding app stays connected. Temporary Access Codes are not issued until an owner or admin sets recovery up again.

Step 7: Test a recovery

Use a non-admin test user in the VK Recovery group.

Supervisor: Help desk → Staff-verified, choose Lost key, enter the test user’s Okta username, confirm the in-person check, and approve with a security key tap. A QR code and link appear, valid for 15 minutes.
Employee: open the link on their own phone or computer. The page shows the device is connected.
HQ help-desk agent: a different VerifiedKnock account approves with its own security key.
The code appears only on the employee’s device. The employee signs out of any Okta session (or uses a private window), signs in with the code, and registers a new passkey.
Remove the employee from VK Recovery afterwards, unless you keep recovery-eligible employees in the group.

Disconnect or remove

VerifiedKnock: Help desk settings → Identity provider → Okta → Disconnect (security key tap). VerifiedKnock deletes its stored onboarding key or client secret, and the recovery key if one was saved.
Option A: Okta → Applications and Resources → API Service Integrations → VerifiedKnock → Revoke. This removes the scopes, Client ID and secret.
Option B: Okta → Applications → VerifiedKnock Help Desk → Deactivate → Delete. If you created VerifiedKnock Recovery, deactivate and delete that app too.
Optional: remove the VerifiedKnock recovery rule from both policies and delete the VK Recovery group.
To replace a client secret: get a new one in Okta (revoke and reinstall), then connect again in VerifiedKnock.

Approver company sign-in

A new branch supervisor or HQ help-desk agent signs in with Okta before registering a security key. Create a separate OIDC web app for that sign-in. It is not the onboarding app in Step 4 or the recovery app in Step 6, and it must not use that app’s client id. Scopes are only openid, profile and email.

Set the web app’s redirect URI to exactly https://pass.verifiedknock.com/v1/helpdesk/approver-oidc/callback. Save that client id and secret in VerifiedKnock under Help desk settings, Identity provider. The secret is stored encrypted and is not shown again.

Onboard approvers

Branch supervisors and HQ help-desk agents must sign in with the company account you invited before they can register a security key. Employees do not need the approver sign-in app and stay out of this group. Use one email per role in the organization. The organization admin should not also be an approver.

In the Okta Admin Console, create a group named VerifiedKnock Approvers.
Create an OIDC web app named VerifiedKnock Approver Sign-In. Scopes are only openid, profile and email. Use authorization code with PKCE. This is not the onboarding or recovery app from Steps 4 and 6, and it must not use either app’s client id. Set the redirect URI to exactly https://pass.verifiedknock.com/v1/helpdesk/approver-oidc/callback. Save that client id and secret in VerifiedKnock under Help desk settings, Identity provider.
Assign the VerifiedKnock Approver Sign-In app to the VerifiedKnock Approvers group. Do not assign it to everyone.
Add each supervisor and HQ help-desk agent to that group with exactly the invited email. The Okta email must match the invite exactly, and the user must be ACTIVE. Leave employees out of the group.
The invited person accepts the invite in a fresh private window, signed in to Okta as that exact user. Personal Microsoft accounts and Gmail accounts are refused.
An owner or admin then confirms that person in Workforce > Approver Security with their own hardware key.

The invite page shows the code in parentheses and says what to do next. When company sign-in returns an email, the page names that account and the invite email. It does not show tokens, user ids, or another person's email. Server logs record which check failed, without tokens or secrets.

Code	What happened	What to do
`IDP_IDENTITY_MISMATCH (email differs)`	The identity provider session is a different person than the invite. A reused Okta or Microsoft session is the usual cause.	Sign out of Okta or Microsoft, or open a private window, then sign in as the invited email.
`IDP_IDENTITY_MISMATCH (email missing)`	Company sign-in did not include an email address.	Confirm the approver sign-in app requests openid, profile, and email, assign the person to that app, then sign in again.
`IDP_IDENTITY_MISMATCH (email not confirmed)`	Okta sent email_verified=false, or Microsoft Entra sent an email without a work sign-in name (UPN).	In Okta, verify the email. In Microsoft Entra, sign in with the UPN on the invite.
`IDP_IDENTITY_MISMATCH (account locked on the invite)`	The invite was issued for one company account, and a different account signed in.	Sign in as that company account, or ask an admin to send a new invite.
`IDP_IDENTITY_MISMATCH (invite already linked)`	This invite is already linked to a company account, and a different account signed in.	Sign in with the account that was used first, or ask an admin to send a new invite.
`IDP_IDENTITY_MISMATCH (already linked elsewhere)`	This company account is already the sign-in for a different approver, or this person is already linked to a different company account.	Ask an admin to check Approver Security. Sign in with the invited person's own company account.
`IDP_TENANT_MISMATCH`	Sign-in came from a different Okta organization or Microsoft tenant, including a personal Microsoft account.	Sign out or open a private window, then sign in to this organization's directory with the work account.
`IDP_USER_NOT_ACTIVE`	The Okta user is not ACTIVE, or Okta could not be checked.	In Okta, set the user to ACTIVE, assign them to the approver sign-in app, then try again.
`IDP_APP_NOT_ASSIGNED`	The company account is not assigned to the approver sign-in app.	Assign that person to the VerifiedKnock Approver Sign-In app. Do not assign the app to everyone. Employees do not need it.
`IDP_CONSENT_REQUIRED`	An admin has not granted consent for the approver sign-in app.	An Okta admin or a Microsoft Entra administrator grants consent, then the invited person signs in again.
`OIDC_SIGNIN_CANCELLED`	Company sign-in was cancelled before it finished.	Return to the invite and choose Sign in with your company account again.
`OIDC_AUTHORIZE_FAILED`	The identity provider did not complete sign-in.	Start again from the invite. If it keeps failing, confirm the redirect URI and client id on the approver sign-in app.
`OIDC_STATE_INVALID`	The sign-in step expired (10 minutes), was already used, or did not include a code.	Start again from the invite in this browser.
`OIDC_STATE_BROWSER_MISMATCH`	Sign-in finished in a different browser than the one that started it.	Open the invite in one browser and finish sign-in there.
`OIDC_TOKEN_EXCHANGE_FAILED`	The identity provider did not return a sign-in token.	Start again. If it keeps failing, ask an admin to check the approver sign-in app secret and assignment.
`OIDC_TOKEN_EXPIRED`	The company sign-in token expired.	Start again from the invite.
`OIDC_TOKEN_AUDIENCE`	Sign-in was issued for a different application.	Use the VerifiedKnock approver sign-in app. Ask an admin to confirm the client id saved in VerifiedKnock.
`OIDC_NONCE_MISMATCH`	Sign-in did not match this invite attempt.	Close old sign-in tabs and start again from the invite.
`OIDC_SUBJECT_MISSING`	Company sign-in did not include a user id.	Start again. The app must request openid, profile, and email.
`IDP_NOT_CONFIGURED`	The organization has no directory connection or no approver sign-in app.	An admin connects the directory and saves the approver sign-in app, then the invited person opens the invite again.
`IDP_SIGNIN_REQUIRED`	A security key was offered before company sign-in.	On the invite page, choose Sign in with your company account first.
`DUPLICATE_IDP_SUBJECT`	This company account is already linked to another approver.	Ask an admin to check Approver Security. Use the invited person's own company account.
`INVITE_INVALID`	The invite link is missing, expired, already accepted, or revoked. The page names which of those the server could see.	Open the link from the invite email. If it is expired, accepted, or revoked, ask an admin to send a new invite.
`KEY_NOT_GENUINE`	The key could not be confirmed as a hardware security key.	Use a hardware security key (for example a YubiKey), then try again.
`PASSKEY_TYPE_REFUSED`	The passkey can sync or be backed up.	Use a hardware security key that stays on one device, then try again.
`CREDENTIAL_CLASS_UNKNOWN`	The security key did not report enough information to register.	Try the hardware key again. If it still fails, ask an admin to confirm the key works with this invite.
`WEBAUTHN_VERIFY_FAILED`	The security key could not be verified.	Try again, and enter the PIN or fingerprint if the key asks. If this key is already registered, use a different key.
`RECOVERY_TOKEN_INVALID`	The Console recovery link is not valid.	Paste the full link, or ask another Console owner to issue a new one.
`RECOVERY_TOKEN_USED`	The Console recovery link was already used.	Ask another Console owner to issue a new link.
`RECOVERY_TOKEN_EXPIRED`	The Console recovery link expired.	Ask another Console owner to issue a new link.
`RECOVERY_CODE_INVALID`	The email and offline recovery code do not match.	Check the offline code and the Console owner email, then try again.
`APPROVER1_NOT_BRANCH_SUPERVISOR`	The person starting recovery is not the branch supervisor for this employee.	Ask that branch supervisor to start it, or use HQ fallback if it is turned on.
`SELF_SERVICE_FORBIDDEN`	An approver tried to approve their own recovery.	Ask a different approver to continue.
`PRIVILEGED_TARGET`	The employee is an organization owner or admin.	Use your organization's privileged-access process for this account.

Troubleshooting

Code or message	What it means	What to do
`OKTA_NOT_ENABLED_FOR_ORG`	Okta is in early access and has not been turned on for your VerifiedKnock organization.	Email [email protected].
`OKTA_CLASSIC_ENGINE_UNSUPPORTED`	Your Okta org runs Classic Engine.	VerifiedKnock needs an Okta Identity Engine org.
`OKTA_CLIENT_ID_INVALID`	The Client ID is not in Okta format.	Copy the Client ID again. It starts with 0oa and has 20 characters.
`OKTA_CLIENT_SECRET_REQUIRED / OKTA_CLIENT_SECRET_INVALID`	The client secret is empty or does not look like an Okta secret.	Paste the secret Okta showed at install. If you no longer have it, revoke and reinstall the integration in Okta to get a new one.
`invalid_client`	Okta did not accept the Client ID and secret (or key).	Check you copied the values from the right Okta org. For a client secret, connect again with a new secret.
`Missing scopes / invalid_scope`	An onboarding or recovery scope is not granted on the app that needs it.	On the onboarding app, grant okta.users.read and okta.roles.read. On the recovery app (or the same app, if you chose that), grant okta.users.manage and okta.authenticators.read. Then click Run check.
`tac_authenticator_not_active / OKTA_TAC_NOT_ENABLED`	The Temporary Access Code authenticator is missing or inactive.	Complete Step 1.
`GRAPH_PERMISSION_MISSING`	Okta refused a read or an action for lack of permission. The action is blocked and nothing changes.	Check the onboarding app (Read-only Administrator, Step 4) and, if recovery is on, the recovery app custom role (Step 6).
`PRIVILEGED_TARGET`	The employee has a directly assigned Okta administrative role.	By design. Recover directly assigned admin-role accounts through your own privileged-access process.
`TARGET_DISABLED`	The employee is suspended, deactivated, staged or not yet active in Okta.	Activate the account in Okta first.
`tac_multi_use`	Okta returned a multi-use code. VerifiedKnock revoked it and stopped.	Turn off multi-use in the Temporary Access Code authenticator (Step 1).
`OKTA_CREDENTIAL_UNUSABLE / OKTA_CLIENT_SECRET_MISSING`	The stored credential cannot be used.	Disconnect and connect Okta again.
`IDP_IDENTITY_MISMATCH`	The company account that signed in is not the invited approver. A reused Okta session, a user who is not assigned to the approver app, or an email that is not an exact match all end here.	The company account that signed in is not the invited person. Sign out of Okta or Microsoft, or open a private window, then sign in as the invited person. A person who is not assigned to the approver sign-in app cannot complete this step. The email must match the invite exactly, and the account must be active.
`IDP_TENANT_MISMATCH`	Company sign-in came from a different Okta organization.	Company sign-in came from a different organization. Sign out of Okta or Microsoft, or open a private window, then sign in to this organization's directory.
`IDP_USER_NOT_ACTIVE`	The Okta user is not ACTIVE, so the invite cannot be accepted.	This company account is not active. In Okta, set the user to ACTIVE and assign them to the approver sign-in app, then sign in again. The email must match the invite exactly.

Okta reuses existing sessions, which can make tests misleading. Sign out of Okta or use a private window before signing in with a code.

Support

Okta early access, setup help and pilots: [email protected]
Security reports: [email protected]
More on the Support page. Microsoft Entra ID instead? See Microsoft Entra ID setup.

Include your organization name, the time (with time zone) and any error code. Never send client secrets, private keys, passwords or Temporary Access Codes.

VerifiedKnock Inc., Fremont, California.