> ## Documentation Index > Fetch the complete documentation index at: https://docs.corbado.com/llms.txt > Use this file to discover all available pages before exploring further. # Explain what went wrong for a user > Explains a user's passkey sign-in or passkey creation attempt for support. Returns what happened, the next step, the supporting signals and whether the user subsequently completed the journey. This feature is available as an add-on and requires activation for your project. To enable it, contact [support@corbado.com](mailto:support@corbado.com). Send the Observe `userID`. By default, the latest supported attempt is selected, excluding silent background checks. Set `onlyFailed` to `true` to select the latest unsuccessful attempt, or send `actionID` to explain a specific attempt. The recovery window defaults to 60 minutes and can be between 1 and 10080 minutes. Check `diagnosis.status` before displaying an answer: `explained` and `worked` include an answer; `no-case-matched`, `no-supported-action` and `no-actions` indicate that no explanation is available. An unknown user returns HTTP 404. See [Support diagnosis](/corbado-observe/passkey-intelligence/support) for the support workflow. Required API key permission: `observe:user:read`. ## OpenAPI ````yaml /api-reference/openapi/observe.yaml post /observe/userDiagnosis openapi: 3.1.1 info: version: 1.0.0 title: Corbado API description: > # Introduction This documentation gives an overview of all Corbado API calls to implement authentication observe. contact: name: Corbado team email: support@corbado.com url: https://www.corbado.com servers: - url: https://api.cloud.corbado.io/v1 security: - bearerAuth: [] tags: - name: ObserveFlow description: Flow search and related APIs x-group: Journeys and users - name: ObserveSubFlow description: Subflow search and related APIs x-group: Journeys and users - name: ObserveUser description: User search and related APIs x-group: Journeys and users - name: ObserveIdentifier description: Identifier search over submitted identifiers x-group: Journeys and users - name: ObservePasskeyIntelligence description: Passkey login predictions and support diagnosis x-group: Passkey Intelligence - name: ObserveClientEnv description: Client environment search APIs x-group: Journeys and users - name: ObserveTimeSeries description: Time series query APIs x-group: Metrics and funnels - name: ObserveFunnel description: Historical funnel metrics, dictionaries and coverage. x-group: Metrics and funnels - name: ObserveEvent description: Event ingestion and event feed APIs x-group: Events - name: ObserveError description: Named authentication errors and recommendations. x-group: Error management - name: ObserveErrorFlavour description: Error variants and their impact on authentication outcomes. x-group: Error management - name: ObserveFinding description: Curated findings that explain errors, their impact and who has to act. x-group: Error management - name: ObserveAlert description: Authentication alert rules, instances and history. x-group: Alert management - name: ObserveAnnotation description: >- Annotations, the project's memory (what is true about the data and how to read it) x-group: Annotations - name: ObserveTableExport description: Table export file listing and download APIs x-group: Data exports - name: ObserveTimeSeriesExport description: Time-series export generation and downloads. x-group: Data exports - name: ObserveDataExport description: Data export APIs x-group: User data - name: ObserveDataDeletionJob description: Data deletion job APIs x-group: User data - name: ObserveFlowTypeDefinition description: Flow type definitions used in authentication journeys. x-group: Catalogs and labels - name: ObserveCatalog description: Catalog APIs x-group: Catalogs and labels - name: OpenAPI description: Downloadable API specification - name: ProjectOperationExecution description: Project-scoped operation history and pipeline health - name: ObserveClassification description: Flow and subflow classification APIs - name: ObserveIntegrationStats description: Integration stats APIs - name: ObserveTimeSeriesPrecalculation description: Time series precalculation APIs - name: ObserveIDList x-group: Saved ID lists description: Stored ID-list selection APIs - name: ObserveDataContext description: Schema-loose data context APIs for agent and debugging tooling - name: ObserveData description: Observe data administration APIs - name: ObserveTrackingStats description: Tracking ingestion stats APIs - name: ObserveProbe description: Raw probe capture items (internal autocapture diagnostics) - name: ObserveTelemetry description: Raw SDK/integration diagnostic telemetry - name: ObserveExperiment x-group: Experiments description: Experiment catalog and run APIs - name: ObserveDataPolicy description: >- Project data policy catalogue (retention selected by the SDK's meta.dataPolicy code) - name: ObserveMetadata x-group: Metadata description: Authenticator metadata APIs (FIDO MDS + passkey AAGUID) - name: ObserveSri description: Subresource Integrity hashes of the scripts Corbado hosts for a project - name: ObservePasskey x-group: Passkey analysis description: Observed passkey search and cohort analysis. paths: /observe/userDiagnosis: post: tags: - ObservePasskeyIntelligence - ObserveUser summary: Explain what went wrong for a user description: >- Explains a user's passkey sign-in or passkey creation attempt for support. Returns what happened, the next step, the supporting signals and whether the user subsequently completed the journey. This feature is available as an add-on and requires activation for your project. To enable it, contact [support@corbado.com](mailto:support@corbado.com). Send the Observe `userID`. By default, the latest supported attempt is selected, excluding silent background checks. Set `onlyFailed` to `true` to select the latest unsuccessful attempt, or send `actionID` to explain a specific attempt. The recovery window defaults to 60 minutes and can be between 1 and 10080 minutes. Check `diagnosis.status` before displaying an answer: `explained` and `worked` include an answer; `no-case-matched`, `no-supported-action` and `no-actions` indicate that no explanation is available. An unknown user returns HTTP 404. See [Support diagnosis](/corbado-observe/passkey-intelligence/support) for the support workflow. Required API key permission: `observe:user:read`. operationId: ObserveUserDiagnosis requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/observeUserDiagnosisReq' responses: '200': description: Explanation and support context for the selected attempt. content: application/json: schema: $ref: '#/components/schemas/observeUserDiagnosis' default: $ref: '#/components/responses/error' security: - bearerAuth: - observe:user:read components: schemas: observeUserDiagnosisReq: type: object required: - userID example: userID: tus-123456 onlyFailed: true properties: userID: type: string description: Observe user ID (format `tus-`), returned by user search. x-oapi-codegen-extra-tags: validate: required,id=tus actionID: type: string description: >- Explain this attempt (format `sfl-`) instead of selecting the latest supported attempt. Takes precedence over `onlyFailed`. The attempt must belong to the requested user's activity. onlyFailed: type: boolean default: false description: >- Select the latest supported attempt that did not complete. Ignored when `actionID` is supplied. recoveryWindowMinutes: type: integer minimum: 1 maximum: 10080 description: >- Time window after the selected attempt's start in which a later successful journey of the same type counts as recovery. Defaults to 60 minutes; accepts 1 to 10080. The attempt's own journey always counts. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=10080 observeUserDiagnosis: type: object required: - diagnosis description: >- Support explanation and the context needed to investigate the selected attempt. properties: diagnosis: $ref: '#/components/schemas/observeUserDiagnosisResult' observeUserDiagnosisResult: type: object required: - status properties: status: type: string description: >- `explained`: a cause and next step are available. `worked`: the selected attempt succeeded. `no-case-matched`: the attempt is available but no explanation applies. `no-supported-action`: no attempt matches the selection. `no-actions`: no recorded actions are available for this user. enum: - explained - worked - no-case-matched - no-supported-action - no-actions focus: $ref: '#/components/schemas/observeUserDiagnosisAction' lastAction: $ref: '#/components/schemas/observeUserDiagnosisAction' case: $ref: '#/components/schemas/observeUserDiagnosisCase' answer: $ref: '#/components/schemas/observeUserDiagnosisAnswer' outcome: $ref: '#/components/schemas/observeUserDiagnosisOutcome' here: $ref: '#/components/schemas/observeUserDiagnosisEnvironment' inventory: type: array description: >- The user's passkeys and their estimated availability from the selected attempt's device. items: $ref: '#/components/schemas/observeUserDiagnosisPasskey' example: status: worked focus: id: '123456' operation: passkey-login start: '2026-10-01T10:00:00Z' completed: true answer: whatHappened: The passkey sign-in completed successfully. nextStep: No action is needed. bucket: reassure outcome: status: finished where: same-flow errorRspV2: type: object required: - error properties: error: type: object required: - message properties: message: description: Error message type: string example: Validation failed details: description: Validation error details per field type: array items: type: object required: - field - message properties: field: description: Field name that failed validation type: string example: projectID message: description: Validation error message type: string example: required observeUserDiagnosisAction: type: object description: >- A recorded attempt. `focus` is the selected attempt; `lastAction` is the latest visible action across sign-in methods and can show what the user tried afterwards. required: - id - operation - start - completed properties: id: type: string description: >- Attempt ID (format `sfl-`); send it as `actionID` to explain this attempt again. operation: type: string description: >- Operation, such as `passkey-login`, `passkey-enrollment` or `password-login`. specType: type: string description: >- How the attempt was initiated, such as `passkey-known-identifier` or `passkey-cui`. start: type: string format: date-time description: Time the attempt started. completed: type: boolean description: Whether this attempt completed successfully. lastError: type: string description: Last recorded error for the attempt, when available. observeUserDiagnosisCase: type: object required: - caseID - confidence - signals properties: caseID: type: string description: >- Machine-readable identifier of the explanation. Additional cases may be added. confidence: type: string description: >- Strength of the evidence for the explanation. Confirm uncertain explanations with the user. enum: - high - medium - low signals: type: array description: >- Recorded or inferred facts supporting the explanation, for further investigation. items: $ref: '#/components/schemas/observeUserDiagnosisSignal' observeUserDiagnosisAnswer: type: object required: - whatHappened - nextStep properties: whatHappened: type: string description: Explanation the support agent can share with the user. nextStep: type: string description: Suggested action or advice for the user's next attempt. bucket: type: string description: >- Support handling: `fix-now` resolves the issue with the user, `explain` explains and redirects, `escalate` passes the case to the identity team and `reassure` confirms no immediate fix is needed. enum: - fix-now - explain - escalate - reassure missingDetails: type: array description: >- Details unavailable for the explanation that the support agent may need to confirm. items: type: string observeUserDiagnosisOutcome: type: object required: - status properties: status: type: string description: >- Whether the user completed the journey containing the selected attempt, or a later journey of the same type within the recovery window. `unknown` means the journey outcome is unavailable. enum: - finished - not-finished - skipped - unknown where: type: string description: >- Whether completion occurred in the selected attempt's journey or a later one. enum: - same-flow - later-flow afterMs: type: integer format: int64 description: >- Milliseconds from the selected attempt's start to completion of the successful journey. observeUserDiagnosisEnvironment: type: object required: - label - inAppBrowser - crossDevice - crossDeviceReason properties: label: type: string description: Readable device, operating system and browser description. deviceName: type: string description: >- Device name for support wording, such as `Windows computer` or `iPhone`. browserName: type: string description: Browser name for support wording, when available. platformAuthenticator: type: boolean description: >- Whether the device reports a built-in passkey authenticator. Omitted when not reported. inAppBrowser: type: boolean description: Whether the attempt ran in a browser embedded in another app. crossDevice: type: string enum: - works - likely - blocked - unknown - not-applicable description: >- Estimated availability of signing in with a phone via a QR code from this device. crossDeviceReason: type: string description: >- Explanation of cross-device availability, including a reported Bluetooth limitation. passwordManagers: type: array description: Password managers observed on the device. items: type: string observeUserDiagnosisPasskey: type: object required: - family - familySource - status - reachHere - reachHereReason properties: passkeyID: type: string description: >- Observe passkey ID (format `tpk-`), as in passkey search. Omitted when only the account's registered passkey families are known. family: type: string description: >- Passkey provider or storage family, such as `apple`, `google` or `windows-hello`. familySource: type: string enum: - aaguid - credential-id-length - usage - allowlist - none description: >- Basis for the family: authenticator metadata (`aaguid`), credential ID characteristics (`credential-id-length`), recorded use (`usage`), the account's offered passkeys (`allowlist`) or no available classification (`none`). provider: type: string description: Readable authenticator or password manager name, when known. createdOn: type: string description: Device and browser where creation was observed. created: type: string format: date-time description: Time the passkey was created, when known. lastUsed: type: string format: date-time description: Time of the latest observed use, when known. status: type: string description: Recorded passkey status, such as `created` or `deleted`. reachHere: type: string enum: - local - cross-device - none - unknown description: >- Estimated availability of this passkey from the selected attempt's device. reachHereReason: type: string description: Explanation of the availability estimate. observeUserDiagnosisSignal: type: object required: - key - value properties: key: type: string description: Name of the supporting fact. value: type: string description: Value or explanation of the fact. source: type: string description: Where the supporting fact came from, when available. responses: error: description: Error content: application/json: schema: $ref: '#/components/schemas/errorRspV2' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Use an Observe API key from the management console. The key selects the project and must grant the permission listed on the operation. Keep this key on your server. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.