Skip to content
/
Service Access and Key En...
Last updated

Service Access & Key Entitlements

This document explains how API key entitlements, service access, and hierarchy context work together in Nelnet Payment Services (NPS).

It clarifies:

  • What access an API key actually grants
  • How Payments vs Reporting access is enforced
  • How hierarchy and entityId affect authorization
  • Common authorization failure scenarios

This page intentionally avoids OAuth-style scope models and documents how NPS works today.

Core Model

Key idea:
Access in NPS is determined by API key entitlements and hierarchy context, not fine-grained scopes.

At a high level:

  • API keys determine what services you can call
  • Hierarchy placement determines which entities you can act for
  • Request fields (such as entityId) determine who you are acting as

API Key Entitlements

When an API key is created in the NPS Portal, it is explicitly associated with one or more services.

Important:
  • An API key can be enabled for one or many services
  • Service access is enforced at request time
  • JWTs cannot grant access beyond what the API key allows

If a key is not entitled for a service, requests to that service will be rejected.

Hierarchy-Based Authorization

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

Key idea:
Keys inherit downward through the hierarchy.

How Hierarchy Affects Access

  • Keys created at a parent level can act for:
    • That parent
    • All child nodes beneath it
  • Keys created at a child level:
    • Are limited to that node only

Hierarchy access is evaluated independently of service entitlement.

Acting as an Entity

Backend API requests specify who the transaction is processed as using the entityId field.

{
  "entityId": 1325691045,
  "transactionType": "SALE",
  "amount": 49.99
}
How this is evaluated:
  • The JWT authenticates the API key
  • The API key’s hierarchy determines which entityIds are allowed
  • The request is processed as the specified entity

This enables platform-style integrations where one credential set processes transactions for many merchants.

Tokenization vs Backend Authorization

Tokenization and backend processing use different authorization mechanisms.

Tokenization (Client-Side)

  • Authorized using a session token
  • Session token is created using a backend JWT
  • Session token:
    • Is short-lived
    • Is scoped only to tokenization
    • Cannot call backend APIs

Backend APIs

  • Authorized using a JWT
  • JWT is signed with an API key
  • JWT access is limited by:
    • Service entitlements
    • Hierarchy placement

Common Authorization Scenarios

ScenarioResult
JWT expired401 Unauthorized
JWT signed with wrong key401 Unauthorized
Key not entitled for serviceAuthorization failure
entityId outside hierarchyAuthorization failure
Tokenization attempted without sessionSDK error
Tip:
Most authorization issues are caused by using the correct key at the wrong hierarchy level, or the right hierarchy with the wrong service entitlement.

Platforms & Marketplaces

  • Create API keys at the parent level
  • Use entityId to specify the merchant context
  • Enable only required services per key

Single-Merchant Integrations

  • Create keys at the merchant level
  • Limit service entitlements to what is needed
  • Use short JWT expiration windows

Environment Separation

  • Use separate API keys for:
    • Production
    • Non-production
  • Rotate keys periodically

What This Is Not

NPS does not currently use:

  • OAuth scopes
  • Role-based access control (RBAC) at the API level
  • Endpoint-level permission configuration

If these models are introduced in the future, they will be documented separately.

Summary

  • API key entitlements determine which services can be accessed
  • Hierarchy placement determines which entities can be acted on
  • JWTs cannot exceed API key permissions
  • entityId controls transaction context
  • Tokenization and backend APIs use different authorization mechanisms
Previous page
Next page