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 behavior 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.

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.
Issued when CSR/certificate is registered during onboarding.
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 Section 3.4.
* SHOULD be provided as an escaped JSON string.
updatedAt
Long(13)

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