REST API Authorization Token (JWT / JWS)

This section defines the Authorization Token used to authorize REST API calls and bind each token to a specific request.

HTTP Transmission

This subsection defines how the Authorization Token is carried in API calls.

The Authorization Token SHALL be transmitted via the HTTP header:

  • Header name: Authorization

  • Scheme: Bearer

  • Format: Authorization: Bearer <JWT>

Compatibility note: Some examples may omit the Bearer scheme for brevity; producers SHOULD send Bearer, and verifiers SHOULD tolerate both formats for backward compatibility.

Payload Binding Rules

This subsection defines the request-binding behaviour required for Authorization Tokens.

The Authorization Token payload binds the token to the exact request using:

  • API.method

  • API.path

Token generators MUST populate these fields using the request that will actually be transmitted, and token validators MUST verify that the bound values match the received request method/path.

The Authorization Token is time-sensitive and SHOULD be used within 30 seconds after creation. It SHOULD be generated only when the actual request is about to be sent. Pre-generating the token may cause timeout or validation errors before the request is processed.

Data Structures (Authorization Token)

JWS Header (Authorization Token)

This subsection defines the required header fields for the Authorization Token.

Field

 Description
alg
String(16)

 (Required)
Signing algorithm
e.g., RS256
cty
String(16)

 (Required)
Content type
Set as "AUTH"
ver
String(4)

 (Required)
Token version
Set as "3"
certificateId
String(64)

 (Required)
Certificate identifier.
Assigned after CSR/certificate registration and can be checked in the Partner Portal.
If multiple certificates are registered, use the certificateId that corresponds to the certificate used
for the request or token.
partnerId
String(16)

 (Required)
Partner identifier assigned at Partner Portal registration (same as partnerCode).
utc
Long(13)

 (Required)
Creation time (epoch ms)
Used for expiry / anti-replay time checks.
i.e., UTC+0

JWS Payload (Authorization Token)

This subsection defines required and optional payload fields for the Authorization Token.

Field

 Description
API
Object

 (Required)
Current API binding object.
API.method
String(8)

 (Required)
HTTP method of the request.
e.g., GET/POST
API.path
String(512)

 (Required)
HTTP path of the request (path only, excluding scheme/host/query).
e.g., /wltex/cards/{cardId}/notification
refId
String(256)

 (Optional)
Unique content identifier defined by the partner.
authentication
String(2048)

 (Optional)
Authentication value.
see Authentication Data Set.
 SHOULD be provided as an escaped JSON string.
updatedAt
Long(13)

 (Optional)
Content update timestamp (epoch milliseconds)
e.g., 1715078400123