Skip to content
/
JWT Authentication
Last updated

JWT Authentication

Nelnet Payment Services (NPS) uses Bearer authentication with JSON Web Tokens (JWTs) for all backend API requests.

This document explains:

  • How JWT authentication works in NPS
  • How to construct and sign a JWT
  • How JWTs are used to create session tokens
  • How authentication and transaction context are separated

Overview

Key idea:
JWTs authenticate who you are. Request fields like entityId determine who you are acting as.

All NPS backend APIs require a short-lived JWT passed in the Authorization header.

Authorization: Bearer <JWT>

JWTs are:

  • Signed using HMAC SHA-512
  • Generated by your backend
  • Created using your API Key ID and API Key

JWTs are never created or used in client-side code.

Authentication Model

NPS authentication follows a simple, layered model:

  • API Key ID → identifies who you are
  • API Key (secret) → proves who you are
  • JWT → short-lived proof of authorization

JWTs are intentionally short-lived and are created on demand by your backend.

JWT Requirements

Signing Algorithm

  • Algorithm: HS512 (HMAC SHA-512)

No custom JWT headers are required. Standard JWT libraries automatically generate the correct header.

JWT Claims

Required Claims

ClaimDescription
subAPI Key ID
iatIssued-at timestamp (seconds since epoch)
ClaimDescription
expExpiration timestamp
Note:
If exp is omitted, the expiration defaults to the value configured when the API key was created.

Example: Creating a JWT (Node.js)

import jwt from 'jsonwebtoken';

function createJwt() {
  const now = Math.floor(Date.now() / 1000);

  const payload = {
    sub: process.env.NPS_API_KEY_ID,
    iat: now,
    exp: now + 300 // 5 minutes
  };

  return jwt.sign(payload, process.env.NPS_API_KEY, {
    algorithm: 'HS512'
  });
}

Creating a Session Token Using a JWT

JWTs are used to authenticate backend requests, including requests that create a tokenization session for use with the NPS JavaScript SDK.

Key idea:
JWTs stay on the server. Session tokens are the only credentials exposed to the browser.

After generating a JWT, your backend requests a session from NPS:

const jwt = createJwt();

const response = await fetch('https://api.nelnetpay.com/tokenization/session', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${jwt}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

return {
  sessionId: data.session.id,
  sessionToken: data.session.token,
  expiresAt: data.session.expiresAt
};

The returned session token is:

  • Short-lived
  • Single-session
  • Safe to return to the browser

Using the JWT in API Requests

JWTs are used for all backend API calls.

POST https://api.nelnetpay.com/payments
Authorization: Bearer <JWT>
Content-Type: application/json

Using the Session Token in the SDK

The session token is used exclusively by the client-side SDK to authorize tokenization within the embedded iframe.

const nps = new NPS({
  sessionId,
  sessionToken,
  onReady: () => console.log('Payment form ready'),
  onTokenizationComplete: handleTokenization,
  onError: handleError
});
Session token characteristics:
  • Authorize tokenization in the browser
  • Are short-lived and single-purpose
  • Cannot be used to call backend APIs

JWT Expiration Behavior

JWT expiration is enforced strictly.

  • Tokens are valid only within their allowed window
  • Expired tokens return 401 Unauthorized
  • Tokens cannot be refreshed — create a new one

Best Practices

  • Use short-lived tokens (1–5 minutes)
  • Generate JWTs on demand
  • Cache briefly if needed, never long-term

API Key–Defined Limits

Each API key defines limits that JWTs cannot exceed:

  • JWT token duration
  • Allowed services (Payments, Reporting)
  • Key start and end dates

JWT claims are validated against these limits at request time.

Platform vs Merchant Authentication

Key idea:
Authentication and transaction context are intentionally separated.

JWTs authenticate who you are, not who you are acting as.

{
  "entityId": 1325691045,
  "transactionType": "SALE",
  "amount": 49.99
}
  • JWT → authenticates the platform or parent entity
  • entityId → specifies the merchant context

This enables secure multi-merchant and platform integrations.

Security Best Practices

  • Store API keys in a secure secrets manager
  • Rotate API keys periodically
  • Never log JWTs or API secrets
  • Use separate keys for production and non-production

Error Responses

If authentication fails, APIs return:

401 Unauthorized

Common causes:

  • Expired JWT
  • Invalid signature
  • Incorrect sub
  • JWT signed with the wrong API key

Summary

  • All backend NPS APIs use Bearer JWT authentication
  • Frontend SDKs use session tokens, not JWTs
  • JWTs are signed using HS512
  • API Key ID → sub
  • API Key → signing secret
  • JWTs are short-lived and non-refreshable
  • entityId controls transaction context, not authentication
Previous page
Next page