Biometric Passkey: Dashboard and API management

Introduction

Biometric Passkey includes management tools for your support, fraud, and investigation teams, delivered as a browser-based management dashboard and a Management API. This guide covers what those teams can do day-to-day through either entry point; both share the same sign-in, authorization, and response-safety rules. For how the management dashboard and Management API are deployed and isolated from the rest of Biometric Passkey, see Biometric Passkey: Deployment.

Access control

Access to the management dashboard and the Management API is controlled by your OIDC provider. Biometric Passkey is registered there as a public OIDC client and does not maintain its own operator accounts; the access tokens your OIDC provider issues are presented to both the management dashboard and the Management API. The sub claim on the access token identifies the operator and is recorded on every audit event the operator's actions produce.

The deployment-time settings referenced below — the management dashboard's public origin, the backend audience identifier, and the JWKS URL — are chosen when you deploy Biometric Passkey. See Biometric Passkey: Deployment for the full configuration list.

OIDC client registration

Register Biometric Passkey in your OIDC provider with the following client configuration. The same registration covers both the management dashboard sign-in and direct Management API calls.

Throughout this section, <your-management-origin> is the public HTTPS origin you assign to the management runtime when you deploy it (for example https://passkey-admin.example.com). The management dashboard derives its redirect URIs from the browser origin it loads on, so both URIs below must be registered exactly as the OIDC provider will see them.

Both /auth/callback and /login are fixed paths owned by the management dashboard; register the full URIs verbatim. The management dashboard returns the operator to /login after sign-out.

Scopes

Every Management API route is gated by exactly one management.* scope. Scopes are independent: a write scope does not imply the matching read scope, and read access to one resource type does not imply read access to another. Scopes are granted to operators in your OIDC provider; Biometric Passkey enforces them on every request based on the access token claims.

The management dashboard hides tabs, action buttons, and navigation entries for scopes the signed-in operator does not hold. An operator who navigates to a route whose required scope is not granted is shown an access-denied page.

If your OIDC provider attaches a fixed prefix to every scope it issues (for example bp_management.users.read instead of management.users.read), configure the same prefix for both authorization and dashboard sign-in. For the exact deployment settings, see Biometric Passkey: Deployment.

• Management API authorization: the backend strips the configured prefix before matching against the canonical management.* scope set.
• Management dashboard sign-in: the management backend emits the configured prefix as oidc.scopePrefix in /runtime-config.json, and the dashboard prefixes canonical management.* scopes before requesting them at sign-in.

For how to call the Management API directly and the common errors that apply to every route, see Management API basics.

Management dashboard

The management dashboard gives support and investigation teams a guided way to investigate users, passkeys, authentication flows, and recent audit activity. It is built for day-to-day triage: start from a user, build context from the user's passkey and visible flow history, take limited passkey lifecycle actions when needed, and leave a retained audit trail for later review.

Find users and start triage

Most investigations start in the User directory. Search by the identifier your system knows as external_user_id, or by the user's first or last name, then open the matching user record.

User search supports these match modes:

• exact or prefix match on external_user_id
• case-insensitive partial match on first and last name

Directory rows show enough context to choose the right record without opening every match: the user name and external ID, the number of passkeys on file, recent flow activity, and the last time the local user record changed.

Build user context

User detail pulls the operational context for one user into a single place. The header identifies the user, shows whether stored encrypted biometric token data is present, and records the workflow run that most recently wrote that token data when available.

The summary cards help an operator decide where to look next: passkeys on file, recent registration/recovery/authentication activity, and visible completed or failed flow records. From the same page, the operator can review the user's passkeys, registration attempts, recoveries, step-up sessions, and retained audit activity. Cross-platform handoffs are visible through linked step-up details and audit context; dedicated cross-platform session lists are available through the Management API.

Review passkey status

The Passkeys tab shows the passkeys known for the user, including lifecycle state, platform, device label, last authentication time, and last update time. Open a passkey to understand whether it is currently usable for Biometric Passkey authentication and how it reached that state.

The passkey detail sheet shows limited operational metadata only: identity, state, lifecycle timestamps, the latest management action when one exists, and retained audit history for that passkey. Sensitive key material is never shown.

Act on a passkey

Use passkey lifecycle actions when a passkey should be temporarily blocked, restored, or permanently retired from Biometric Passkey authentication.

• Suspend changes an active passkey to suspended. Suspended passkeys are excluded from normal authentication use until reactivated.
• Activate changes a suspended passkey back to active.
• Revoke changes an active or suspended passkey to revoked. Revoked passkeys are terminal and cannot be reactivated.

Each action requires a reason_code and accepts an optional reason_text operator note. Repeating the same action against a passkey already in the target state returns the current state, so retried operator actions do not create a second transition.

Passkey actions change the local Biometric Passkey credential state. Use your relying-party procedures for any account remediation that must happen outside Biometric Passkey.

Investigate user journeys

Flow history helps operators review how a user moved through enrollment, recovery, in-app step-up, or the step-up leg of a cross-platform handoff. Each flow row starts from the outcome and timing, then the detail sheet adds the identifiers and workflow references needed to connect the report to backend logs or case notes.

Flow detail sheets show metadata only: status, error code, lifecycle timestamps, workflow run references, linked passkeys where applicable, and the linked step-up session for cross-platform handoffs when available. Sensitive tokens, challenges, assertions, and raw WebAuthn payloads are not shown.

Dashboard flow investigation is read-oriented. Administrative cleanup for an in-progress registration is handled through the Management API and is covered in Clean up registration attempt.

Trace what happened

The Audits view is the cross-user investigation trail. Use it to answer who or what acted, which resource was involved, what the result was, and which correlation or workflow reference connects related events.

Quick filters cover the most common triage cuts: event domain and result. Advanced filters narrow the timeline by time range, source channel, event type, actor, correlation ID, registration attempt, step-up session, cross-platform session, or workflow run.

User detail and passkey detail also link back into retained audit history, so an operator can move from a specific user or passkey into the broader event trail without restarting the investigation.

Delete local user data

Use the dashboard delete action only when the local Biometric Passkey record for a user must be removed. The action is destructive, requires a reason code, and accepts an optional operator note so the retained audit trail explains why the deletion happened.

Deleting a user removes live local Biometric Passkey records for that user. Retained audit history is not deleted, and successful delete events snapshot the removed passkey identifiers for later investigation.

This dashboard action is not a replacement for account remediation in external systems. Use those systems' own procedures for records outside Biometric Passkey.

Management API basics

The Management API is served under the versioned base path /api/management/v1. Every request is authenticated and gated by a single management.* scope, as described in Calling the Management API.

These conventions apply to every route:

• Pagination — list endpoints are cursor-paginated; limit defaults to 50 and is capped at 100, and you page by following next_cursor.
• Timestamps — all timestamps are RFC 3339 UTC strings.
• Path identifiers — path parameters always use the internal Biometric Passkey UUIDs (user_id, biometric_passkey_credential_id, registration_attempt_id, recovery_attempt_id, km_passkey_session_id, cross_platform_session_id).
• WebAuthn credential ID — the raw WebAuthn credential_id is a response field, not a path key.

Calling the Management API

The Management API accepts the same access tokens issued for the management dashboard. The access token is presented on every request in the Authorization header:

1GET /api/management/v1/users HTTP/1.1
2Host: <your-management-origin>
3Authorization: Bearer <access_token>
4X-Correlation-ID: <optional-correlation-id>

The token must be issued by the OIDC issuer Biometric Passkey is configured for, carry the configured audience, include valid exp, iat, and nbf time claims, and carry the management.* scope required by the route. The required scope for each route is documented with the endpoint below. X-Correlation-ID is optional and is preserved on every audit row the request produces; reuse it across related calls to keep an investigation trail.

Common errors

Two error codes are common to every Management API route. Other error codes are documented with the endpoint that emits them. All error responses share the same envelope:

1{
2  "error": {
3    "code": "INSUFFICIENT_SCOPE",
4    "message": "The access token is missing a required management scope.",
5    "retryable": false
6  }
7}

Branch on error.code rather than parsing error.message. Consult error.retryable to decide whether to retry; 4xx codes are always non-retryable unless documented otherwise.

Response safety boundaries

Management API responses expose limited operational metadata only. They never include:

• encrypted biometric token (EBT) ciphertext
• finalize tokens
• cached SDK tokens
• handoff tokens, continuation tokens, recovery tokens
• raw attestation objects or raw assertion signatures
• raw client_data_json
• raw JWTs or bearer tokens
• raw WebAuthn challenge values

Audit details payloads are restricted to an allowlist of safe references: registration_attempt_id, recovery_attempt_id, step_up_auth_session_id, cross_platform_session_id, workflow_run_id, channel, provider_status, required_scope, resume_denial_reason, selected_recovery_credential_id, replacement_biometric_passkey_credential_id, idempotency_key_present, prior_biometric_used, and deleted_biometric_passkey_credential_ids.

Automation reuse

The same scoped Management API may be reused by your own automation for narrow post-recovery credential cleanup after a successful recovery finalize. A typical sequence is:

1. GET /api/management/v1/users?query=<external_user_id> — resolve the internal user_id from your canonical user identifier. The caller must select exactly one returned user whose external_user_id matches the value you sent.
2. GET /api/management/v1/users/{user_id}/credentials — enumerate the user's passkeys, excluding the replacement passkey just minted by recovery.
3. POST /api/management/v1/credentials/{biometric_passkey_credential_id}/revoke — revoke each prior credential your recovery policy targets. Use a stable reason_code such as recovery_replaced and reuse the recovery X-Correlation-ID so the audit trail links the cleanup to the recovery event.

Use the matching scoped endpoint when your policy prefers to suspend rather than revoke prior credentials.

User endpoints

These endpoints cover summary counts and the user search, detail, and deletion workflow. The summary endpoint is grouped with users because it shares the management.users.read scope.

1GET /api/management/v1/summary HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4X-Correlation-ID: <YOUR_CORRELATION_ID>

1GET /api/management/v1/users?query=doe&limit=50 HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4X-Correlation-ID: <YOUR_CORRELATION_ID>

1GET /api/management/v1/users/<USER_ID> HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4X-Correlation-ID: <YOUR_CORRELATION_ID>

1DELETE /api/management/v1/users/<USER_ID> HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4Content-Type: application/json
5X-Correlation-ID: <YOUR_CORRELATION_ID>
6
7{
8  "reason_code": "user_requested_deletion",
9  "reason_text": "User submitted a verified deletion request via support ticket #4821."
10}

Credential endpoints

These endpoints cover passkey inspection and lifecycle management. The OAuth scope identifiers retain the credentials naming for stability on the wire; the management dashboard labels the same resource for operators as passkey. Lifecycle transitions are documented in Passkey detail and lifecycle.

1GET /api/management/v1/users/<USER_ID>/credentials?limit=50 HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4X-Correlation-ID: <YOUR_CORRELATION_ID>

1GET /api/management/v1/credentials/<BIOMETRIC_PASSKEY_CREDENTIAL_ID> HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4X-Correlation-ID: <YOUR_CORRELATION_ID>

1POST /api/management/v1/credentials/<BIOMETRIC_PASSKEY_CREDENTIAL_ID>/suspend HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4Content-Type: application/json
5X-Correlation-ID: <YOUR_CORRELATION_ID>
6
7{
8  "reason_code": "fraud_investigation",
9  "reason_text": "Holding credential while reviewing case #7821."
10}

1POST /api/management/v1/credentials/<BIOMETRIC_PASSKEY_CREDENTIAL_ID>/activate HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4Content-Type: application/json
5X-Correlation-ID: <YOUR_CORRELATION_ID>
6
7{
8  "reason_code": "investigation_cleared",
9  "reason_text": "Case #7821 closed; restoring credential."
10}

1POST /api/management/v1/credentials/<BIOMETRIC_PASSKEY_CREDENTIAL_ID>/revoke HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4Content-Type: application/json
5X-Correlation-ID: <YOUR_CORRELATION_ID>
6
7{
8  "reason_code": "device_lost",
9  "reason_text": "User reported lost device on 2026-05-21."
10}

Registration attempt endpoints

These endpoints cover read-only inspection and administrative cleanup of in-progress registration attempts. All read endpoints require management.flows.read; cleanup requires the separate management.flows.cleanup scope.

1GET /api/management/v1/users/<USER_ID>/registration-attempts?limit=50 HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4X-Correlation-ID: <YOUR_CORRELATION_ID>

1GET /api/management/v1/registration-attempts/<REGISTRATION_ATTEMPT_ID> HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4X-Correlation-ID: <YOUR_CORRELATION_ID>

1POST /api/management/v1/registration-attempts/<REGISTRATION_ATTEMPT_ID>/cleanup HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4Content-Type: application/json
5X-Correlation-ID: <YOUR_CORRELATION_ID>
6
7{
8  "reason_code": "operator_cancel",
9  "reason_text": "User abandoned IDV; closing stale attempt."
10}

Step-up auth session endpoints

These endpoints cover read-only inspection of in-app step-up auth sessions. Required scope on every route: management.flows.read.

1GET /api/management/v1/users/<USER_ID>/step-up-auth-sessions?limit=50 HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4X-Correlation-ID: <YOUR_CORRELATION_ID>

1GET /api/management/v1/step-up-auth-sessions/<BIOMETRIC_PASSKEY_SESSION_ID> HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4X-Correlation-ID: <YOUR_CORRELATION_ID>

Cross-platform session endpoints

These endpoints cover read-only inspection of cross-platform (desktop-to-mobile handoff) sessions. Required scope on every route: management.flows.read.

1GET /api/management/v1/users/<USER_ID>/cross-platform-sessions?limit=50 HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4X-Correlation-ID: <YOUR_CORRELATION_ID>

1GET /api/management/v1/cross-platform-sessions/<CROSS_PLATFORM_SESSION_ID> HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4X-Correlation-ID: <YOUR_CORRELATION_ID>

Recovery attempt endpoints

These endpoints cover read-only inspection of account recovery attempts. Required scope on every route: management.flows.read.

1GET /api/management/v1/users/<USER_ID>/recovery-attempts?limit=50 HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4X-Correlation-ID: <YOUR_CORRELATION_ID>

1GET /api/management/v1/recovery-attempts/<RECOVERY_ATTEMPT_ID> HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4X-Correlation-ID: <YOUR_CORRELATION_ID>

Audit event endpoints

These endpoints cover read-only access to recent retained audit events. Required scope on every route: management.audit.read. Results are returned in insertion-stable newest-first order with a cursor for pagination; each item also carries occurred_at as the business event timestamp. Audit timelines remain available after the live row keyed by user_id or biometric_passkey_credential_id has been hard-deleted, because the audit row stores the logical reference. Requests outside the supported retained-history window return 400 AUDIT_QUERY_OUT_OF_RANGE.

1GET /api/management/v1/audit-events?domain=management&result=succeeded&limit=50&from=2026-05-01T00:00:00Z&to=2026-05-22T00:00:00Z HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4X-Correlation-ID: <YOUR_CORRELATION_ID>

1GET /api/management/v1/users/<USER_ID>/audit-events?limit=50 HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4X-Correlation-ID: <YOUR_CORRELATION_ID>

1GET /api/management/v1/credentials/<BIOMETRIC_PASSKEY_CREDENTIAL_ID>/audit-events?limit=50 HTTP/1.1
2Host: <YOUR_MANAGEMENT_BASE_URL>
3Authorization: Bearer <YOUR_MANAGEMENT_ACCESS_TOKEN>
4X-Correlation-ID: <YOUR_CORRELATION_ID>

Related guides

• Biometric Passkey: Deployment
• Biometric Passkey: Core API integration
• Biometric Passkey: SDK integration
• Biometric Passkey: Version policy
• Biometric Passkey: FAQ