Gateway (OIDC) Integration

Overview

The ID Dataweb Gateway is an OpenID Connect (OIDC)-based integration layer that lets you trigger identity verification workflows from any application that supports redirects. ID Dataweb hosts and serves the verification UI; your application redirects the user, receives an authorization code when verification is complete, and exchanges it for a signed ID Token containing the policy decision.

This is the lowest-effort integration path. No custom UI is required, and most OIDC-compatible SSO systems can connect without custom code.

How It Works

sequenceDiagram
    participant User
    participant YourApp as Your Application
    participant Gateway as ID Dataweb Gateway
    participant Checkers as Checkers

    YourApp->>Gateway: GET /authorize (client_id, redirect_uri, scope)
    Gateway->>User: Present verification workflow UI
    User->>Gateway: Complete verification steps
    Gateway->>Checkers: Verify identity attributes
    Checkers-->>Gateway: Results & assertions
    Gateway->>YourApp: Redirect with authorization code
    YourApp->>Gateway: POST /token (exchange code)
    Gateway-->>YourApp: ID Token (JWT with policyDecision)

Step 1: Authorize

(GET) https://preprod.iddataweb.com/axn/oauth2/authorize

Your application initiates verification by redirecting the user to the /authorize endpoint with the required parameters.

const redirect = () => {
    window.location.href = (
      `https://preprod.iddataweb.com/axn/oauth2/authorize?` +
      `response_type=code&` +
      `scope=openid&` +
      `client_id=${'your-workflow-api-key'}&` +
      `redirect_uri=${'your-redirect-uri'}&` +
      `state=foobar`
    )
}

Parameters

Step 2: User Completes Verification

After the redirect, the user is presented with the configured verification workflow hosted by ID Dataweb. Depending on your workflow configuration, the user may complete one or more steps — for example, submitting PII, verifying a phone number via OTP, or completing a document capture.

Step 3: Receive Authorization Code

When the user completes the workflow, ID Dataweb redirects to your redirect_uri with a one-time authorization code:

https://your-app.example.com/callback?state=foobar&code=SplxlOBeZQQYbYS6WxSbIA

Step 4: Exchange Code for ID Token

(POST) https://preprod.iddataweb.com/axn/oauth2/token

Exchange the authorization code for an ID Token containing verification results.

Request

const axios = require('axios')

const getToken = async (auth, authCode) => {
  const response = await axios({
    url: "https://preprod.iddataweb.com/axn/oauth2/token",
    method: "POST",
    data: {
      grant_type: 'authorization_code',
      code: authCode,
      redirect_uri: auth.redirect_uri,
      client_id: auth.apikey,
      client_secret: auth.secret
    },
    headers: {
      accept: 'application/json',
      "Content-Type": "application/x-www-form-urlencoded",
      "Cache-Control": "no-cache",
    },
  })
  return response.data
}

Response

{
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJzdWIiOiJ...",
  "access_token": "SlAV32hkKG",
  "token_type": "Bearer",
  "expires_in": 3600
}

Verify the ID Token signature. It is strongly recommended that your application verifies the JWT signature before trusting any data it contains. ID Dataweb signs tokens using RS256. Public keys are available at the JWKS endpoint listed in the Well-Known / Discovery Endpoints section below.

Scopes

Scopes customize the authorization request. Multiple scopes are delimited with +.

Example with multiple scopes

https://preprod.iddataweb.com/axn/oauth2/authorize
  ?client_id=123456
  &redirect_uri=https://your-app.example.com/callback
  &scope=openid+country.US
  &response_type=code
  &state=abc123

Well-Known / Discovery Endpoints

The ID Dataweb Gateway exposes standard OIDC Discovery endpoints. Most frameworks with native OIDC support can consume these automatically to configure authorization, token, and JWKS endpoints.

Supported parameters

• Response types: code
• Client authentication methods: client_secret_post (secret sent in POST body) and HTTP Basic Auth

Prefill / Login Hint

Prefilling user attributes into the verification workflow removes friction — the user sees their information already populated when they arrive. You do this by passing a login_hint JWT in the /authorize request.

Before using any prefill option: Enable Login Hint on your workflow API key in the Admin Console.

Option 1 — Admin API JWT Generation (Recommended)

Call the ID Dataweb Admin API with the user's PII. The API generates and returns a fully formed, properly signed JWT. Append it as the login_hint parameter on your /authorize URL.

This is the simplest option — no JWT library required on your end. Contact your ID Dataweb team for Admin API credentials and the endpoint reference.

GET /authorize
  ?client_id=your-api-key
  &redirect_uri=https://your-app.example.com/callback
  &scope=openid
  &response_type=code
  &state=abc123
  &login_hint=<jwt-from-admin-api>

Option 2 — Build Your Own JWT

Construct the JWT in your application using the ID Dataweb PII payload format. The payload contains the user attributes you want to prefill:

{
  "sub": "user-credential-or-id",
  "fname": "Jane",
  "lname": "Smith",
  "phone": "5551234567",
  "dob": "01/15/1985",
  "email": "[email protected]",
  "addressline1": "123 Main St",
  "city": "Springfield",
  "state": "IL",
  "postalcode": "62701",
  "country": "US"
}

Signing options:

Use encryption whenever the login_hint will be visible in browser history or server logs.

Option 3 — Federated Login Prefill

Add a federated identity provider (IDP) to the beginning of your workflow. The user authenticates with your IDP first, and their attributes are automatically mapped and passed into the ID Dataweb verification flow — no manual JWT construction required.

How it works:

1. User clicks "Verify" in your app
2. ID Dataweb redirects the user to your configured IDP (e.g. Google, Okta, your own SSO)
3. User authenticates with the IDP
4. IDP returns attributes to ID Dataweb via standard OIDC/SAML assertions
5. Mapped attributes are prefilled into the verification workflow

Contact your ID Dataweb team to configure IDP attribute mapping for your workflow.

Testing

Use the preproduction environment during development and testing:

• Authorization endpoint: https://preprod.iddataweb.com/axn/oauth2/authorize
• Token endpoint: https://preprod.iddataweb.com/axn/oauth2/token
• Well-Known: https://preprod.iddataweb.com/axn/oauth2/.well-known/openid-configuration

Preproduction API keys are available from the Admin Console. Test data and workflows are available in your preproduction environment.

Error Handling

OIDC errors are returned as query parameters on the redirect_uri:

https://your-app.example.com/callback?error=access_denied&error_description=...

Common error codes include access_denied, invalid_request, and server_error. For a full list of OIDC error codes and recommended handling, see the Troubleshooting section in the Reference documentation.