Hybrid Integration

Overview

Hybrid Integration lets you start a verification flow through the ID Dataweb Gateway (OIDC) and then continue it via the ID Dataweb API — on the same session. This is useful when you want the simplicity of the Gateway for initial verification steps, but need API-level control (or access to additional checks) for later steps.

The key to this pattern is the Application Session Identifier (ASI). The ASI established during the Gateway /authorize flow carries through to subsequent API calls, maintaining a unified session and transaction trail.

This pattern is also rule-based: you can configure workflows with mixed obligation types so that Gateway-only users and Hybrid users are served from the same workflow without disrupting each other.

To enable Hybrid Integration, contact your ID Dataweb team. The Obligation type=API must be configured in your workflow's policy manager.

How It Works

sequenceDiagram
    participant User
    participant YourApp as Your Application
    participant Gateway as ID Dataweb Gateway
    participant IDWAPI as ID Dataweb API

    YourApp->>Gateway: GET /authorize
    Gateway->>User: Present Gateway verification steps
    User->>Gateway: Complete Gateway steps
    Gateway->>YourApp: Redirect to callback (Obligation type=API — no final decision yet)
    YourApp->>IDWAPI: POST /slverify (using same ASI from Gateway session)
    IDWAPI-->>YourApp: policyDecision (approve/deny)

Standard Gateway Flow vs. Hybrid Flow

Standard Gateway flow:

1. Your application calls /authorize.
2. The user progresses through the workflow — the Gateway handles obligations internally.
3. After the final step, the user is redirected to your redirect_uri with an approve or deny decision.

Hybrid flow:

1. Your application calls /authorize.
2. The user progresses through the Gateway-hosted steps.
3. When an Obligation type=API is reached, the Gateway redirects the user to your callback URL without a final approve or deny decision — the flow is intentionally left open.
4. Your application receives the redirect with the ASI from the Gateway session.
5. Your application calls /slverify (or other API endpoints) using the same ASI, submitting additional attributes or triggering additional checks.
6. The API returns the final policyDecision.

Session Continuity

The ASI from the /authorize request is the same transaction_id used in API calls. Pass it as the asi field in your API request body:

{
  "asi": "<ASI from Gateway session>",
  "apikey": "your-next-step-api-key",
  "credential": "[email protected]",
  "userAttributes": [
    // additional attributes for API step
  ]
}

This ensures that all Gateway and API steps are associated with a single session in reporting, billing, and Admin Console analytics.

Mixed Rules

Because Hybrid configuration is rule-based, you can set up a single workflow with different obligation types for different rule paths. For example:

• Users who meet a certain risk threshold complete the flow entirely within the Gateway (approve/deny returned directly).
• Users who require additional verification are obligated via type=API, and your application continues the session with API calls.

This means you do not need separate workflows for Gateway-only and Hybrid users.

Setup Summary

1. Contact your ID Dataweb team to enable Obligation type=API on your workflow.
2. Configure your callback URL in the workflow to handle both standard OIDC returns (with policyDecision) and Hybrid returns (without a final decision).
3. Detect the Hybrid return in your callback: when no policyDecision is present (or a specific obligation indicator is present), proceed with API calls using the session ASI.
4. Use the same session-tracking pattern as standard API flows — pass asi in all subsequent API calls.