> ## 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. # Predict the passkey login outcome > Recommends how to route a passkey login before the browser opens the passkey prompt: start normally (`local`), prepare the user to sign in with a phone (`phone`), try once (`try-once`) or use another sign-in method (`fallback`). Call server to server from your identity provider or login backend after identifying the account. 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 context from the login browser unchanged, for example the value of its `cbo_observe_context` cookie, and the account's credential IDs. Registration details are optional. At least one credential is required; each credential array accepts at most 50 entries. When device information is unavailable, the response has `verdict: local`, `reason: session-not-ready` and `environment.source: none`. In that case, or without an Observe context, continue with your existing login behavior. Set a bounded HTTP timeout and continue with that same behavior on errors or timeouts; do not wait for retries of this call during the login. The verdict is a recommendation, not a guarantee of passkey availability. Apply `retryPolicy` to passkey attempts, not HTTP requests. See [Prevent failed passkey logins](/corbado-observe/passkey-intelligence/prevent-failed-logins) for integration steps and the PingAM example. Required API key permission: `observe:passkeys:read`. ## OpenAPI ````yaml /api-reference/openapi/observe.yaml post /observe/passkeyIntelligence 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/passkeyIntelligence: post: tags: - ObservePasskeyIntelligence summary: Predict the passkey login outcome description: >- Recommends how to route a passkey login before the browser opens the passkey prompt: start normally (`local`), prepare the user to sign in with a phone (`phone`), try once (`try-once`) or use another sign-in method (`fallback`). Call server to server from your identity provider or login backend after identifying the account. 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 context from the login browser unchanged, for example the value of its `cbo_observe_context` cookie, and the account's credential IDs. Registration details are optional. At least one credential is required; each credential array accepts at most 50 entries. When device information is unavailable, the response has `verdict: local`, `reason: session-not-ready` and `environment.source: none`. In that case, or without an Observe context, continue with your existing login behavior. Set a bounded HTTP timeout and continue with that same behavior on errors or timeouts; do not wait for retries of this call during the login. The verdict is a recommendation, not a guarantee of passkey availability. Apply `retryPolicy` to passkey attempts, not HTTP requests. See [Prevent failed passkey logins](/corbado-observe/passkey-intelligence/prevent-failed-logins) for integration steps and the PingAM example. Required API key permission: `observe:passkeys:read`. operationId: ObservePasskeyIntelligenceEvaluate requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/observePasskeyIntelligenceReq' responses: '200': description: >- Login recommendation, reason, passkey retry policy and device-information source. content: application/json: schema: $ref: '#/components/schemas/observePasskeyIntelligenceRsp' default: $ref: '#/components/responses/error' security: - bearerAuth: - observe:passkeys:read components: schemas: observePasskeyIntelligenceReq: type: object required: - observeContext description: >- Send the user's passkeys either as plain IDs (`credentialIDs`) or with what the identity provider stored at registration (`credentials`), or both; at least one credential is required. Every field beyond the credential ID is optional and only fills what Observe does not know itself. properties: observeContext: type: string description: >- Opaque Observe context from the login browser, for example its `cbo_observe_context` cookie value. Pass it unchanged; do not construct or decode it. Without it, skip this call and continue with your existing login behavior. Maximum 1024 characters. x-oapi-codegen-extra-tags: validate: required,min=1,max=1024 credentialIDs: type: array description: >- Base64url or base64 credential IDs of the account's passkeys. At most 50 entries, each up to 1400 characters. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,max=50,dive,min=1,max=1400 credentials: type: array description: >- The user's passkeys with the registration data the identity provider stored. Use instead of or together with `credentialIDs`; for the same credential ID these details are used. At most 50 entries. items: $ref: '#/components/schemas/observePasskeyIntelligenceCredentialInput' x-oapi-codegen-extra-tags: validate: omitempty,max=50,dive observePasskeyIntelligenceRsp: type: object required: - verdict - reason - retryPolicy - environment example: verdict: phone reason: phone-needed retryPolicy: maxTries: 3 switchAfterInstantFailure: true environment: source: session properties: verdict: type: string description: >- Recommended route: `local` starts the passkey login normally; `phone` prepares the user for a phone and QR code; `try-once` allows one attempt with the fallback visible; `fallback` starts another sign-in method. For `reason: session-not-ready`, retain your existing login behavior. enum: - local - phone - try-once - fallback reason: type: string description: >- Why this route is recommended. Route by `verdict`; use `reason` for wording and reporting. More reasons may be added. | Verdict | Reason | Meaning | |---|---|---| | `local` | `passkey-on-this-device` | A passkey is expected on this device. | | `local` | `phone-possible` | A passkey may be here or on a phone; start normally, do not announce a phone. | | `local` | `session-not-ready` | No device information yet: continue with your existing login behavior. | | `phone` | `phone-needed` | The passkey is most likely on a phone: prepare the user for a QR code. | | `try-once` | `uncertain` | The passkey may not work here: allow one attempt with the fallback visible. | | `fallback` | `passkey-not-on-this-device` | None of the passkeys can be used on this device. | | `fallback` | `bluetooth-off` | The passkey is on a phone and this computer reports Bluetooth off; the user may turn it on. | | `fallback` | `phone-sign-in-unavailable` | The passkey is on a phone and this browser offers no sign-in with a phone. | | `fallback` | `no-passkey-support` | This device cannot use passkeys. | | `fallback` | `in-app-browser` | The login runs in a browser embedded in another app. | | `fallback` | `failed-on-this-device` | Recent passkey attempts of this account failed on this device. | retryPolicy: $ref: '#/components/schemas/observePasskeyIntelligenceRetryPolicy' environment: $ref: '#/components/schemas/observePasskeyIntelligenceEnvironment' observePasskeyIntelligenceCredentialInput: type: object required: - credentialID properties: credentialID: type: string description: Base64url (or base64) credential ID. x-oapi-codegen-extra-tags: validate: required,min=1,max=1400 transports: type: array description: >- Transports stored for the passkey at registration (`getTransports()`), such as `internal` or `hybrid`. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,max=8,dive,min=1,max=32 backupEligible: type: boolean description: >- Backup eligibility (BE) flag of the authenticator data at registration. aaguid: type: string description: Authenticator AAGUID from the attestation at registration. x-oapi-codegen-extra-tags: validate: omitempty,uuid registrationUserAgent: type: string description: User agent of the request that registered the passkey. x-oapi-codegen-extra-tags: validate: omitempty,max=1000 observePasskeyIntelligenceRetryPolicy: type: object required: - maxTries - switchAfterInstantFailure properties: maxTries: type: integer description: >- Passkey tries before switching to the fallback (0 = start with the fallback). switchAfterInstantFailure: type: boolean description: Switch to the fallback after a failure within 3 seconds. observePasskeyIntelligenceEnvironment: type: object required: - source properties: source: type: string description: >- Source of the device information used for the recommendation: `session` uses the current browser session, `clientEnv` uses information from an earlier visit on the device and `none` means no device information is available. With `none`, retain your existing login behavior. enum: - session - clientEnv - none 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 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.