# API Keys & Account Hierarchy

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

Key idea:
Identity (API keys) and behavior (configuration) both follow the hierarchy.

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

Important behavior:
Keys created at a 
parent
level can be used for all child nodes
Keys created at a 
child
level apply only to that node
The breadcrumb in the portal shows where you are 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)**


Important:
The API Key secret is shown 
only once
.
  Store it securely.

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:

```json
{
  "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