API Keys & Account Hierarchy

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

This guide explains how API keys, JWT authentication, and the account hierarchy work together in Nelnet Payment Services (NPS).
It also walks through how to generate API keys in the NPS Portal and how to use parent-level credentials to act on behalf of child entities.

Core Concepts

Account Hierarchy

NPS accounts are organized into a hierarchy:

• Parent nodes (platforms, institutions, or partners)
• Child nodes (merchants, sub-clients)

Each node in the hierarchy has a unique Entity ID.

Configuration & Inheritance

Most configuration in NPS is hierarchical and inheritable.

• Configuration set at a parent level is inherited by all children
• Child nodes may override specific settings if allowed
• Examples of hierarchical configuration:
  • Payment methods
  • Fraud rules
  • CAPTCHA enforcement
  • Surcharge behavior

While configuration inheritance is managed separately from API keys, it follows the same hierarchy model.

API Keys in NPS

What API Keys Are Used For

API keys are used to:

• Create JWTs for Bearer authentication
• Call backend APIs (Payments, Reporting)
• Create tokenization sessions for the browser

A single API key pair consists of:

• API Key ID → used as the JWT sub
• API Key (secret) → used to sign the JWT

Where API Keys Live in the Hierarchy

API keys are always created at a specific node in the hierarchy.

How to Generate API Keys

Step 1: Request Portal Access

1. Request access from Client Services or Technical Support
2. Portal URL:
   https://portal.nelnetpay.com
3. You will receive an email invite
4. Follow the instructions in the email to activate your account

Step 2: Select the Correct Hierarchy Node

Before creating a key:

1. Log in to the portal
2. Click Hierarchy in the left navigation
3. Navigate to the desired node (parent or merchant)
4. Confirm the breadcrumb shows the correct location

Keys are attached to the node you are currently viewing.

Step 3: Create the API Key

1. Select API Key Management in the left navigation
2. Click the + button on the right
3. Fill out the form:
   • Key Name
   • JWT Token Duration (in seconds)
   • Associated Services
4. Submit the form

Step 4: Save the Key Material

A modal will display:

• API Key ID
• API Key (secret)

These values are used to create JWTs for authentication.

Step 5: Confirm Key Status

After creation:

• The key should appear as ACTIVE
• You can view:
  • Associated services
  • Expiration dates
  • Last 6 characters of the key

Using API Keys with the Hierarchy

Acting on Behalf of Child Entities

For example when making a Payments API call, you can specify the entity you are acting as:

{
  "entityId": 1325691045,
  "transactionType": "SALE",
  "amount": 49.99
}

• The entityId corresponds to a node in the hierarchy
• This allows:
  • Parent-level keys to process payments for child merchants
  • Centralized credential management

Tokenization vs Processing Context

It is valid to:

• Tokenize using parent-level credentials
• Process the payment at the merchant level using entityId

Example flow:

1. Platform creates tokenization session at parent level
2. Browser tokenizes payment data
3. Backend submits payment using merchant entityId

This supports:

• Marketplaces
• PayFac models
• Multi-merchant platforms

Summary

• API keys are created and scoped to hierarchy nodes
• Parent keys can act on behalf of child entities
• JWTs are created using API Key ID + API Key
• entityId controls who the transaction is processed as
• Configuration and behavior inherit through the same hierarchy