VerifiedKnock · Documentation

Okta setup

Help-desk account recovery with Okta Temporary Access Codes. Okta support is in early access: email founders@verifiedknock.com 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.

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 users with an Okta admin 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 founders@verifiedknock.com), 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.

Okta API scopes

All four are required. VerifiedKnock uses the Okta org authorization server and the OAuth 2.0 client credentials flow.

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.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; GET /api/v1/groups/{id}/roles`	Refuse recovery for anyone who holds an Okta admin role, directly or through a group.
`okta.authenticators.read`	`GET /api/v1/authenticators`	Confirm the Temporary Access Code authenticator exists and is active before any 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: Limit code sign-in to a recovery group

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: Give VerifiedKnock access to Okta

VerifiedKnock supports two ways to sign in to Okta. Choose one.

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.

Okta Admin Console → Applications and Resources → API Service Integrations → Add Integration. Select VerifiedKnock and click Next.
Review the requested 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 the four scopes above.
After Step 5, paste the public key VerifiedKnock shows into General → Client Credentials → Public keys → Add key.

Admin permissions

Okta checks the app’s admin role as well as its scopes. Creating a Temporary Access Code needs the Okta permission to manage Temporary Access Codes. For your own API service app, assign a role on its Admin roles tab. If the integration installed from the Okta Integration Network shows an Admin roles tab in your org, assign the same role there.

Least privilege: a custom admin role that can view users, manage Temporary Access Codes, and reset or remove authenticators, limited to a resource set containing the VK Recovery group.
VerifiedKnock also reads role assignments to refuse admin accounts. If a permission is missing, the check or the first action reports GRAPH_PERMISSION_MISSING and nothing changes.
Do not turn on Public client app admins. It makes the app a super admin.

Step 5: Connect Okta 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 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 Okta.
Click Run check. VerifiedKnock gets a token, confirms all four scopes, and confirms the Temporary Access Code authenticator is active. It reads no user data. When everything passes, the status is Connected.

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: 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 key or client secret.
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.
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.

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 founders@verifiedknock.com.
`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`	One or more of the four scopes is not granted.	Grant all four scopes (custom app), or reinstall and approve all requested scopes (Okta Integration Network).
`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. Every help-desk action is blocked (fail closed).	Check the scopes and the admin role assigned to the VerifiedKnock app (see Admin permissions).
`PRIVILEGED_TARGET`	The employee holds an Okta admin role.	By design. Recover admin 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.

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: founders@verifiedknock.com
Security reports: security@verifiedknock.com
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.