Skip to main content

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 methodDescription
Redirect integrationRedirect 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 integrationNot supported. Contact your Account Manager for more information

Integration steps​

  1. Create a session via API
  2. Obtain playerUrl from the API response
  3. redirect the user to the playerUrl

Create a session​

Call the API to create a session.

info

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

Handling redirect URLs​

To automatically redirected the user after the session completes, pass an optional redirectUrl when you Create a session. The backend will only accept and store this redirectUrl after validating that it matches one of the OAuth client’s configured Allowed redirect URLs. If it’s not on the allowlist, the request is rejected.

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://player.eu.platform.idnow.io/?token=eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..."
}

URL structure​

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

https://player.eu.platform.idnow.io/?token=[token]

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
  • Required flow execution ID missing → BAD_REQUEST

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:

  1. Create a flow session via API call
  2. Read the playerUrl from the API response
  3. Redirect the user to playerUrl
  4. User completes verification
  5. 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​

info

The Player cannot currently be embedded as an iframe and may have restrictions depending on the workflow context. Please reach out to your account manager for more information.