API Authentication and Digital Signature - E2E Trust Token

E2E Trust Token - JSON Web Token

API Authentication - JSON Web Token (JWT) Validation

The Client Id Token for all HSBC Taas API's, is a signed JWT. It is used for authentication and must be provided in the header of the HTTP request every time you invoke Taas services. This ensures only authorised and pre-approved organisations can access and utilise our API services.

JSON Web Token structure

Let's see what a typical JSON Web Token looks like:

The format represents a header, payload and signature.

hhhhh.ppppp.sssss

#	Part	Description	Format
1	Header	The header consists of the version, PGP key ID, type of token and the signature algorithm being used.	hhhhh
2	Payload	The payload consists of private claims such as the client's profile id, client's Encrypted HTTP payload and registered/ public claims such as audience and timestamp.	ppppp
3	Signature	Crypto-text generated by the signature algorithm which consists of: Encoded Header and Payload Client's private credentials	sssss

Part

Description

Format

Header

The header consists of the version, PGP key ID, type of token and the signature algorithm being used.

hhhhh

Payload

The payload consists of private claims such as the client's profile id, client's Encrypted HTTP payload and registered/ public claims such as audience and timestamp.

ppppp

Signature

Crypto-text generated by the signature algorithm which consists of:

Encoded Header and Payload
Client's private credentials

sssss

Fields in a JSON Web Token

The table below lists the parameters and descriptions of a signed JSON Web Token

Part	Parameter	Description	Example Value	Logical Structure (Before Encoding)
1. Header	ver	HSBC private claim. The customer MUST set it as "1.0".	1.0	{ "ver": "1.0", "kid": "ABCD123456789012", "typ": "JWT", "alg": "PS256" }
	kid	Public Key Id which HSBC uses to verify the JWT signature. Using this key Id, HSBC reads the public key from the PGP key file provided to our customers.	ABCD123456789012
	typ	Token Type. This must be set to "JWT"	JWT
	alg	To verify the signature on the token, only the algorithms below are supported. Note: We recommend the PS256, PS384, and PS512 algorithms over the other RSA algorithms. The PKCS#1.5 padding scheme (RS256, RS384, and RS512) does not provide a high enough level of security and should be replaced by the PSS padding scheme.	PS256
2. Payload	sub	Identifies the subject of the JWT. The Customer must provide the "API Profile Id" value delivered in the secure email sent by HSBC.	1234567890	{ "sub": "1234567890", "aud": "RECEIPIENT", "payload_hash_alg": "RSASHA256", "payload_hash": "01a234567bc8901d2345ef67gh73d430e70052d2bb64ba11e6caee3816eb40d", "iat": 1642492971, "jti": "ff59eaea-156f-40e9-9658-17eedcf9b21e" }
	aud	Identifies the intended recipients for the JWT.	RECIPIENT
	payload_hash	Hashing value of the HTTP encrypted request payload body. This is used by the gateway policy for validation.	RSASHA256
	payload_hash_alg	Hashing algorithm of the payload_hash. Algorithm supported: SHA-256/SHA-384/SHA-512	01a234567bc8901d2345ef67gh73d430e70052d2bb64ba11e6caee3816eb40d
	iat	Issued at time. This identifies the time at which the JWT was issued. The value must be a NumericDate.	1642492971
	jti	A case sensitive, unique identifier of the token. If the application uses multiple issuers, there is a negligible probability that the same value will be accidentally assigned to a different data object. Collisions must be prevented among values produced by different issuers. The "jti" claim can be used to prevent the JWT from being replayed. The "jti" value is a case-sensitive string.	ff59eaea-156f-40e9-9658-17eedcf9b21e
3. Signature	N/A	Sign the JWT header and payload and sign using the algorithm defined in "alg"	N/A	PS256( base64UrlEncode(header) + "." + base64UrlEncode(payload), clientPrivateCredentials))

A complete JWT looks like this:

JWT Token

JWT implementation Example

You can find a detailed implementation guide here: https://develop.hsbc.com/knowledge-article/tutorial-and-guides

Tutorials and Guides

Lean more about JWT