Welcome to our new developer portal! Use the "Ask" button to chat with our AI Agent.
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Build authentication token

Overview

The digital wallet backend must build an authentication token in the following cases:

  • To support green flow enrollment.

  • To provide additional wallet data (issuer risk scoring).

The digital wallet backend signs the authentication token with its private key.

NFC Wallet backend validates the token with the corresponding public key provided during onboarding.

Green flow enrollment

The token proves that issuer has previously authenticated the end user and approved the Tokenization request.

Additional wallet data

The authentication token lets the digital wallet provide additional data securely. It helps ensure that no intermediary alters the additional data.

See Provide additional wallet data.

Authentication token requirements

The authentication token is a JWT (RFC 7519).

JWT is a standard format for transmitting signed claims between systems.

Supported algorithms

NFC Wallet backend supports these signature algorithms:

  • RS256

  • PS256

  • PS512

JWT format

A JWT contains three Base64URL-encoded parts separated by dots (.):

  • Header

  • Payload

  • Signature

The compact format is:

<header>.<payload>.<signature>

The header defines the token type and signature algorithm.

kid is required. NFC Wallet backend uses it to select the correct public key.

Header example:

Base64URL-encode the header as a single line before generating the signature.

Payload

The payload supports these claims:

Field
Required
Description

iss

Required

Issuer identifier. Use the issuerId assigned during onboarding.

sub

Conditional

Required only if nonce is present in the encrypted card data. Set the value to the SHA-256 hash of the nonce.

iat

Required

Token issuance time, formatted as defined in RFC 7519.

exp

Required

Token expiration time, formatted as defined in RFC 7519.

wallet

Optional

Additional wallet data in JSON payload format. See Provide additional wallet data.

Payload example:

In the example above, sub is b776ce1e1b00be3f03c7fff59d872c32cfd65cc4377766f47af84f48ea8925f2. It is the SHA-256 hash of the nonce value abdda9cfbe2fdce335290773ba6f56a9c5ebe64910.

Signature

Compute the signature over the Base64URL-encoded header and payload with the issuer backend private key.

NFC Wallet backend validates the signature with the public key provided during onboarding.

The final JWT is the concatenation of the encoded header, payload, and signature, separated by dots.

Generate the JWT

You can use any JWT library that supports RSA signatures and custom headers.

This example uses the jose4j Java library:

See JWT libraries by language for supported implementations.

Last updated

Was this helpful?