Securing and running mainframe APIs
An API opens the mainframe to callers you have never met. Securing it means encrypting traffic, proving who the caller is, mapping that identity to a RACF user so existing access rules still apply, and watching how the API is used.
Layers of protection
Encryption
Every API connection uses TLS. On z/OS, AT-TLS can add encryption in the network stack, so applications need no TLS code, and policies are managed centrally.
From token to RACF
Callers usually present an OAuth access token or a JWT issued by an identity provider. The gateway or z/OS Connect validates it and maps the caller to a RACF user ID. From then on, the request is checked against the same RACF profiles as a terminal user, and the audit trail shows a real identity rather than one shared technical account.
Running APIs day to day
- Rate limits at the gateway protect CICS from traffic spikes or runaway clients.
- Versioning — publish breaking changes as
/v2/and keep/v1/running until consumers have moved. - Monitoring — track response time, error rates and calls per client; correlate with CICS statistics and SMF records.
- Correlation IDs — pass one ID from the gateway into the program's logs, so one request can be traced end to end.
| Symptom | Likely layer |
|---|---|
| 401 Unauthorized | Token missing or expired |
| 403 Forbidden | Token valid, but RACF denies the resource |
| Timeouts under load | CICS capacity, DB2 contention or missing rate limits |
| TLS handshake failure | Expired or untrusted certificate |
Common mistakes
It removes accountability and gives every caller the same broad access. Map callers to appropriate RACF IDs.
Logs are read by many people and kept for a long time. Log IDs and outcomes, not secrets or customer details.
Renaming a field breaks every app that uses it. Add fields freely, but publish breaking changes as a new version.
What you will see at work
- Security reviews for new APIs are standard; be ready to explain which RACF ID each call runs under and what it can access.
- 403 versus 401 is a common first-line triage question: 401 is about the token, 403 is about permissions.
- Certificate renewals are planned work. Missing one causes outages that look like network failures.
Key terms
Check your understanding.
Take this lesson's quiz and save your progress. Free.