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

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

| Scenario | Result |
|  --- | --- |
| JWT expired | `401 Unauthorized` |
| JWT signed with wrong key | `401 Unauthorized` |
| Key not entitled for service | Authorization failure |
| `entityId` outside hierarchy | Authorization failure |
| Tokenization attempted without session | SDK 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.

## Recommended Patterns

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