Trust Model
Three parties are involved when a merchant uses your app.| Party | Role | Trusts |
|---|---|---|
| JTL Platform | Issues credentials, verifies tokens, enforces scopes, hosts merchant data | Cryptographic proof (JWT signatures, client secrets) |
| Your app | Authenticates with JTL, reads and writes tenant data within granted scopes | Tokens issued by JTL; session claims verified via JWKS |
| Merchant (tenant) | Grants scopes at install time, owns the data | The platform to enforce scope and tenant boundaries |
Platform Security
The platform enforces the following security guarantees. These are platform-level properties and do not require configuration in your app.Authentication
How the platform verifies the identity of your app and the user’s session.- OAuth 2.0 client credentials. Your backend obtains access tokens from the Identity Provider using your
clientIdandclientSecret. Tokens are signed JWTs with a one-hour lifetime. - Session token verification via JWKS. When your frontend (loaded inside ERP Cloud) passes a session token to your backend, your backend verifies it against the platform’s JWKS endpoint:
https://api.jtl-cloud.com/account/.well-known/jwks.json. Tokens that fail signature verification are rejected. - HTTPS enforced. All platform endpoints require HTTPS. HTTP requests are rejected.
Authorization
What an authenticated request is allowed to do, enforced at the API layer.- Scope-based access control. API resources require specific scopes. A token presented without the required scope is rejected at the API layer, not at your application layer.
- Tenant isolation. Every Cloud API request must include
X-Tenant-ID. The platform enforces that the presenting app may only access data belonging to the specified tenant, and only tenants that have installed the app.
Operational Security
The platform protects itself at runtime through the following:- API monitoring. JTL monitors endpoint consumption, error rates, and request frequency across all apps. Anomalous patterns may trigger investigation.
- Credential revocation. JTL may revoke API credentials without prior notice if unauthorized use is suspected. This is a platform-level protection against compromised secrets.
- Change notification commitments. General API modifications (minor or breaking changes) are announced in advance. Emergency fixes for security incidents, critical errors, or external partner changes may be applied with less or no notice, with notification sent after the fact. For detail, see versioning.
Your Responsibilities
The platform protects its boundaries. Everything inside your app’s boundary is your responsibility. The following checklist covers what every Cloud App should do.Credentials
YourclientId and clientSecret authenticate your app to the platform. Treat them as secrets.
-
Never ship
clientSecretto the browser. The secret belongs on your backend only. If it appears in frontend code, network requests, or a public repository, treat it as compromised and recreate it immediately in the Partner Portal. - Store secrets in a secrets manager or environment variables. Not in source code, not in config files committed to version control.
- Share credentials on a need-to-know basis. Internal personnel, contractors, and external developers may access credentials only when their role requires it, and only when bound to the API License Terms.
- Notify JTL immediately if credentials are lost or compromised. Contact partner@jtl-software.com. The client secret can be regenerated; the client ID stays the same.
Token Handling
Access tokens and session tokens are the credentials your app uses at runtime. Both need deliberate handling.-
Verify every session token before trusting the tenant it claims. Fetch the platform’s JWKS, verify the JWT signature, check expiry. Never trust the
tenantIdin a session token payload without first verifying the signature. -
Cache access tokens with a safety buffer. Refresh before the token’s
expclaim with a 60-second margin, not after it expires. - Don’t log tokens. Access tokens and session tokens are credentials. Exclude them from application logs, error reports, and analytics.
Scopes
Scopes define what your app can do on a merchant’s behalf.-
Request the minimum scopes your app actually uses. Broader scopes mean broader blast radius if your app is compromised. Declare only what you need in
capabilities.erp.api.scopes. - Treat scope requests as user-visible. Merchants see the scopes you request at install time. Over-requesting damages trust and install conversion.
Application Security
The platform secures its boundaries. Inside your app, you’re responsible for the fundamentals.- Serve your app over HTTPS. The platform requires it, and iframe embedding inside ERP Cloud will fail without it.
- Validate input from AppBridge messages. Messages from the shell are still untrusted input. Validate types, bounds, and expected values before acting on them.
- Handle tenant boundaries correctly. If your app stores data keyed by tenant, every query and write must include the tenant ID from the verified session token. A bug here is a cross-tenant data leak.
Incident Response
What to have in place before an incident and how to respond when one occurs.- Maintain an incident response plan. Third-party providers must have an incident response plan for both privacy/security breaches and operational disruptions. JTL may request a copy during an audit.
- Report security incidents promptly. If your app experiences a data breach or suspected compromise affecting merchant data, report to partner@jtl-software.com and to affected merchants per your data processing obligations.
Data Handling and GDPR
Merchant data processed through the JTL Platform often qualifies as personal data under the GDPR. Customer names, contact information, order history, and transaction details are all personal data. This affects what your app can do with that data and what agreements must be in place.Your Role Under GDPR
Your role depends on the relationship between your app and the merchant.| Your role | When it applies | Your obligation |
|---|---|---|
| Independent data processor | You provide an app that merchants install and use independently | Enter into a data processing agreement (DPA) directly with each merchant using your app. The merchant is the controller; you are their processor. |
| JTL’s data processor | You were engaged by JTL to build, operate, or maintain a JTL product | Enter into a data processing agreement with JTL. JTL remains the processor for the merchant; you are a sub-processor. |
Data Minimisation
GDPR favours holding less data for less time. The platform can’t enforce this for you; it’s a property of how your app handles data once it has it.- Only fetch the data your app needs. Broad scopes and over-fetching create GDPR risk that you’re responsible for, not the platform.
- Don’t persist data longer than necessary. If your app can operate statelessly or with short-lived caches, prefer that over indefinite storage.
- Respect deletion requests. When a merchant uninstalls your app or requests data deletion, delete the data you hold on their behalf within a reasonable period.
Reporting Security Issues
If you discover a vulnerability in the JTL Platform, report it to partner@jtl-software.com rather than disclosing it publicly. For security issues in your own app affecting merchant data, follow the incident response guidance above.What’s Next
OAuth 2.0 flow
Full detail on client credentials and session token flows.
Versioning
API versioning and breaking change commitments.
Best Practices
Production readiness checklist for Cloud Apps.