> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopae.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Methods

> Choose the right integration approach for your use case

## Overview

hConnect offers two integration methods: a hosted OIDC flow (redirect to Hopae's OpenID Provider) and direct API integration. Each has distinct trade-offs in security, complexity, and control.

## Architecture Comparison

<Tabs>
  <Tab title="Hosted OIDC Flow">
    ### OAuth 2.0 Authorization Code Flow

    Follows the standard OIDC Authorization Code flow for simplified yet secure integration:

    <Info>
      **Fully OIDC-Compliant**: The hosted flow uses the OIDC Authorization Code grant (with PKCE support) against the `https://connect.hopae.com` issuer, so you can reuse any OIDC-certified client library.
    </Info>

    1. Redirect users to `https://sandbox.connect.hopae.com/auth` (or production)
    2. hConnect handles all provider interactions
    3. Receive an authorization code on your redirect URI
    4. Exchange code for ID token

    ### Key Security Features

    * **PKCE**: Protection against code interception
    * **State Parameter**: CSRF protection
    * **Single-use codes**: 60-second TTL
    * **JWT ID Tokens**: Standard token format

    ### Implementation Example

    ```javascript theme={null}
    const authUrl = new URL('https://sandbox.connect.hopae.com/auth');
    authUrl.searchParams.append('client_id', CLIENT_ID);
    authUrl.searchParams.append('redirect_uri', REDIRECT_URI);
    authUrl.searchParams.append('response_type', 'code');
    authUrl.searchParams.append('scope', 'openid profile');
    authUrl.searchParams.append('state', crypto.randomUUID());
    authUrl.searchParams.append('code_challenge', codeChallenge);
    authUrl.searchParams.append('code_challenge_method', 'S256');
    ```
  </Tab>

  <Tab title="REST API (Direct Integration)">
    ### Direct Provider Integration

    Full control with increased implementation complexity:

    1. Create verification session via API
    2. Handle provider-specific flows (QR/Push/Redirect)
    3. Implement custom UI for each flow type
    4. Poll for verification status
    5. Retrieve verified attributes

    ### Implementation Requirements

    * Server-side credential management
    * Provider-specific flow handling
    * Custom session state management
    * Polling with exponential backoff

    ### Example: Multi-Flow Handling

    ```javascript theme={null}
    // Handle different provider flows
    switch(response.flowType) {
      case 'redirect':
        window.location.href = response.flowDetails.redirectUrl;
        break;
      case 'qr':
        generateQRCode(response.flowDetails.qrData);
        startPolling(response.verificationId);
        break;
      case 'push':
        showPushUI(response.flowDetails);
        startPolling(response.verificationId);
        break;
    }
    ```
  </Tab>
</Tabs>

## Provider Flow Comparison (Example)

| Provider | Flow Type | Hosted OIDC Flow | API Requirements        |
| -------- | --------- | ---------------- | ----------------------- |
| FrejaID  | QR Code   | ✅ Automatic      | QR generation + polling |
| MitID DK | Redirect  | ✅ Automatic      | Redirect handling       |
| Smart-ID | Push      | ✅ Automatic      | Push UI + polling       |

<Info>**Provider Abstraction**: The hosted OIDC flow abstracts provider differences. Direct API integration requires implementing each provider's specific flow.</Info>

## Key Differences

| Aspect                  | Hosted OIDC Flow             | API                      |
| ----------------------- | ---------------------------- | ------------------------ |
| **Security Model**      | OAuth 2.0 patterns with PKCE | Custom implementation    |
| **Provider Complexity** | Abstracted away              | Direct handling required |
| **Implementation Time** | Quick setup                  | Extensive development    |
| **Control Level**       | Standard flow                | Full customization       |
| **Maintenance**         | Automatic updates            | Manual updates           |

## Next Steps

<CardGroup cols={2}>
  <Card title="OIDC Integration" icon="id-card" href="/guides/oidc-integration">
    Hosted OIDC flow guide
  </Card>

  <Card title="API Integration" icon="code" href="/guides/api-integration">
    Direct API integration guide
  </Card>
</CardGroup>