Embed or redirect

Integrate Player into your frontend application

Before integrating with Player, ensure that all prerequisites are fulfilled as described in the Quickstart guide.

Integration method

Integration method	Description
Redirect integration	Redirect users to the IDnow-hosted Player URL for a full-screen verification experience with guaranteed camera/microphone access (if permission is given by user).
Embedded integration	Embed the Player within your web application using an iframe or webview to keep users on your domain while maintaining your UI context.

Integration steps

Create a session via API
Obtain playerUrl from the API response
Either redirect the user to the playerUrl or embed it as the src of your iframe or webview

Create a session

Call the API to create a session.

info

For complete API documentation, request examples, and implementation details, see Create session.

Obtain `playerUrl`

When you create a flow session via the API, the response provides a playerUrl that includes a token as a query parameter. The token is a JWE (JSON Web Encryption) generated using the jose library and encrypted with a 256-bit symmetric key. It is used by the Player for authentication and expiration of the flow session.

{
  "playerUrl": "https://localhost:3000/player?token=eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0...",
}

URL structure

The playerUrl already includes a token in query parameter and can be used directly by the frontend.

https://player-trustplatform.idnow.io/player/?token=[token]

Encrypted Token payload

Only IDnow can decrypt this token.

Field	Description
`iss`	Token issuer. Default value is `hub-core-api`
`sub`	Subject carrying the workflow identifier (an internal flow identifier)
`aud`	Token audience. Default value is `hub-player`
`exp`	Expiration timestamp in seconds. Used to compute `expiresAt` and `expiresIn`
`iat`	Issued-at timestamp in seconds. Used together with `exp` to compute `expiresIn`
`jti`	Flow session identifier (`sessionId`)

Token lifetime

The token lifetime is always synchronized with the Session lifetime

By default, it is set to 24 hours. If the Session lifetime will be configured shorter or longer, the token will expire accordingly.

Token validation

When the Player interacts with the IDnow backend, the token is validated before processing. The system checks the issuer (iss), audience (aud), and expiration (exp).

Missing or invalid token → UNAUTHORIZED (Missing or invalid authentication token)
Required workflowId missing → BAD_REQUEST (workflowId is required)

Choose integration method

Redirect integration

This is the simplest and most reliable integration method where the user is directed to the IDnow-hosted Player.

Process:

Create a flow session via API call
Read the playerUrl from the API response
Redirect the user to playerUrl
User completes verification
Monitor completion via webhooks or polling

Web browser:

// Web browser
// playerUrl is returned by the API and already contains ?token=<sdkToken>
window.location.href = playerUrl;

Mobile app (iOS)

// playerURL is returned by the API and already contains ?token=<sdkToken>
let playerURL = "<PLAYER_URL_FROM_API>"
if let url = URL(string: playerURL) {
    UIApplication.shared.open(url)
}

Mobile app (Android):

// playerURL is returned by the API and already contains ?token=<sdkToken>
String playerURL = "<PLAYER_URL_FROM_API>";
Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(playerURL));
startActivity(intent);

Advantages:

Full screen experience for users
No iframe restrictions
Camera/microphone access guaranteed
Handles all verification types seamlessly

Use when:

You want the simplest integration
User experience is the priority
You don't need to maintain UI context during verification

Embedded integration

Embed the IDnow-hosted Player within your web application for a seamless in-app experience.

Implementation steps:

Create a flow session via API call
Read the playerUrl from the API response
Embed the Player in an iframe using the returned playerUrl
Handle completion via callback URL or postMessage events

Basic iframe implementation:

<!-- After creating flow session via API -->
<!-- playerUrl already contains ?token=<sdkToken> -->
<iframe
  id="idnow-player"
  src="<PLAYER_URL_FROM_API>"
  style="width: 100%; height: 600px; border: none;"
  allow="camera; microphone; geolocation; fullscreen"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
/>

Advanced iframe with event handling:

<div id="verification-container" style="width: 100%; height: 600px;">
  <iframe
    id="idnow-player"
    src="<PLAYER_URL_FROM_API>"
    style="width: 100%; height: 100%; border: none;"
    allow="camera; microphone; geolocation; fullscreen"
    sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
  />
</div>

Responsive iframe setup:

.verification-iframe-container {
  position: relative;
  width: 100%;
  height: 0;
  padding-bottom: 56.25%; /* 16:9 aspect ratio */
}

.verification-iframe {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  border: none;
}

Current limitations:

Some mobile browsers may restrict camera access in iframes
Requires explicit permissions in iframe allow attribute
PostMessage communication may be limited (depends on implementation)

Use when:

You need to maintain your application UI
Verification is part of a larger form/process
Users should not leave your domain

Integrate Player into your frontend application​

Integration method​

Integration steps​

Create a session​

Obtain playerUrl​

URL structure​

Encrypted Token payload​

Token lifetime​

Token validation​

Choose integration method​

Redirect integration​

Embedded integration​