Here’s a fully structured **design specification** based on everything we’ve discussed regarding migrating SuiteX/iPaaS to OAuth 2.0 M2M with certificate creation and rotation. I’ve addressed all four criteria and written it technically enough for the engineering team to begin architecture.

---

# Design Spec: SuiteX OAuth 2.0 M2M Migration & Certificate Rotation

## 1. Quantified Business Value (The "Why")

**Objective:** Transition SuiteX integrations from TBA (Token-Based Authentication) to OAuth 2.0 M2M (Client Credentials) with certificate-based authentication, reducing operational overhead, improving security, and enabling fully automated API interactions.

**Measurable Outcomes:**

* **Operational efficiency:** Eliminates ~5–10 hours per week per account team previously spent manually refreshing TBA tokens.
* **Scalability:** Supports multi-tenant integrations without human intervention for token refresh; enables onboarding of 10× more accounts without proportional staffing increases.
* **Security & compliance:** Aligns with SOC2 / enterprise security standards by using per-tenant certificate pairs with enforceable rotation policies.
* **Reliability:** Reduces integration downtime caused by expired TBA tokens (currently up to 7 days). Expected reduction of failed API calls due to authentication errors by 90%.

**ROI:** Operational savings + reduced support incidents + ability to support Enterprise-tier integrations that require fully automated token management.

---

## 2. Defined User Experience (The "Who" and "What")

**User Personas:**

1. **Integration Admin (Customer)**

   * Sets up NetSuite integration record
   * Uploads public certificate provided by iPaaS
   * Confirms successful token generation

2. **iPaaS System (Internal / Automated)**

   * Generates JWT per request or per token refresh window
   * Exchanges JWT for short-lived access token
   * Caches access token for subsequent API calls

---

**Step-by-Step User Flow:**

### **Tenant Onboarding Flow (Phase 1 / MVP)**

1. **Integration Record Setup**

   * Admin creates an integration in NetSuite.
   * System provides a **public certificate** (PEM/CRT format) to upload.

2. **Certificate Upload & Role Mapping**

   * Admin uploads public certificate to NetSuite integration record.
   * Admin maps integration to a role with necessary permissions.

3. **Token Verification**

   * iPaaS generates a test JWT signed with private key.
   * Exchanges JWT for access token.
   * Verifies token can call NetSuite API successfully.

4. **Caching**

   * Access token stored temporarily (expires in ~60 min minus buffer).
   * Subsequent API calls reuse token until expiration.

---

### **Key Rotation Flow**

1. **Generate new key pair (iPaaS system)**

   * Private key stored securely (encrypted at rest).
   * Public key provided to customer for NetSuite upload.

2. **Add new certificate in NetSuite**

   * Customer uploads new public cert to existing integration record.
   * Both old and new certs valid simultaneously.

3. **Switch signing key**

   * System begins signing JWTs with new private key.
   * Old key remains in NetSuite for overlap window.

4. **Verify functionality**

   * Run test token exchange to confirm API calls succeed with new key.

5. **Remove old certificate**

   * After successful verification, customer deletes old public cert from NetSuite.

---

**Inputs / Outputs**

| Input                              | Output                                        |
| ---------------------------------- | --------------------------------------------- |
| Tenant ID, integration record info | Stored mapping in iPaaS                       |
| Private key (generated)            | JWT signed per request                        |
| Public key (uploaded to NetSuite)  | Access token from NetSuite token endpoint     |
| Token expiry info                  | Cached access token in Redis/memory           |
| Certificate rotation trigger       | System switches signing key and updates cache |

---

**Wireframes / Visuals**

* Diagram attached (optional) showing:

```
[Private Key] --signs--> [JWT] --> [NetSuite Token Endpoint] --> [Access Token] --> [API Call]
[Public Key] uploaded in NetSuite to verify JWT
Rotation: overlap of old/new certs
```

---

## 3. Strict Scope Boundaries (The "MVP Limit")

**In Scope (Phase 1):**

* Migrate existing TBA-based integrations to OAuth 2.0 M2M.
* Generate per-tenant key pairs.
* Provide public certificate to customer for NetSuite integration record upload.
* Implement token caching & automated JWT signing.
* Implement certificate rotation process with overlap window.

**Out of Scope (Phase 1 / Future Enhancements):**

* Programmatic upload/remove of certificates via NetSuite API.
* Automatic rotation triggers without customer involvement.
* Multi-key rotation scheduling.
* User-facing UI for monitoring expired tokens.
* Role-specific permission validation beyond baseline integration role.

**MVP Rule:** Anything requiring automation of NetSuite-side certificate upload or deletion is a “Fast Follow” item.

---

## 4. Behavioral Acceptance Criteria

### **Authentication & Token Management**

1. **Token Generation**

   * JWT signed with correct private key yields valid access token.
   * Access token expires after ~60 minutes (minus buffer).

2. **Token Caching**

   * System reuses token until expiration.
   * Expired token triggers automatic JWT refresh.

3. **Invalid Key / Token**

   * If JWT signed with unrecognized key → NetSuite returns 401 → system logs error and retries using valid key.

---

### **Certificate Rotation**

1. **Add new key**

   * Both old and new certs must be valid during overlap period.
   * API calls succeed with new key while old key remains in NetSuite.

2. **Switch signing**

   * All JWTs generated after switch use new private key.
   * Old key not used for new JWTs.

3. **Remove old certificate**

   * After verification, old cert removed → only new key is active.
   * Any remaining use of old key results in access errors.

---

### **Edge Cases / Unhappy Paths**

* **Customer fails to upload public cert** → token generation fails → system logs error, notifies tenant admin.
* **Token request fails (network / NetSuite endpoint)** → retry with exponential backoff.
* **Access token expired before use** → request fails → system automatically regenerates JWT and requests new token.
* **Concurrent rotations** → system uses locking mechanism to prevent multiple signing keys being used simultaneously.
* **Shared vs per-tenant key misconfiguration** → system detects invalid key version and alerts.

---

# Summary / Key Principles

* **M2M flow replaces TBA**: no human intervention needed for day-to-day token generation.
* **Per-tenant certificate pairs**: private key stays internal, public key uploaded in NetSuite.
* **Rotation safe & auditable**: overlap period ensures zero downtime.
* **Token caching**: avoids unnecessary JWT/token requests per API call.
* **Clear MVP boundaries**: manual NetSuite upload remains; future automation is optional.

---

# Diagram

```mermaid
flowchart TD
    subgraph JWT_Token_Flow["Token Generation & API Call"]
        A[Private Key (iPaaS)] -->|Sign JWT| B[JWT]
        B -->|Request Access Token| C[NetSuite Token Endpoint]
        C -->|Return Access Token| D[Cache Access Token]
        D -->|Use Token| E[NetSuite API Call]
    end

    subgraph Rotation_Flow["Certificate Rotation"]
        F[Generate New Key Pair (iPaaS)] --> G[New Public Cert]
        G -->|Upload to NetSuite Integration Record| H[NetSuite Integration Record]
        H --> I[Old + New Certificates Active]
        I --> J[Switch JWT Signing to New Private Key]
        J --> K[Test Token Exchange / API Call Success]
        K --> L[Remove Old Public Cert from NetSuite]
        L --> M[New Key Only Active]
    end

    %% Connect main flow to rotation
    D -->|Token expired / rotation needed| F
```