Using a Personal Access Token (PAT) w/Zowe CLI

4 min readApr 25, 2024

{Core} Boris Petkov wrote a great intro to Personal Access Tokens for the Zowe API Mediation Layer (API ML). Here we’ll show an example of obtaining a Personal Access Token (PAT) and using it to make requests to services registered in the API ML with Zowe CLI.

Available Services

We’ll start by accessing three services which are available in the API ML gateway:

Generating a PAT

You can generate a PAT calling the API endpoints through something like cURL or some other HTTP client tool in this format:

$ curl -u ibmuser:password -X POST https://zowe.gateway.net:1024/gateway/api/v1/auth/access-token/generate -d "{""validity"":90,""scopes"":[""ibmzosmf"",""bcmopsrestapiga""]}"

A few notes for this request:

the validity for this token will be 90 days
we’re intentionally excluding the NetMaster API in the scopes field (for demonstration purposes later)
you can find the scopes (service IDs) to use by clicking an individual service within the API Catalog UI, for example:

Service ID for OPS used for the scopes parameter

Upon running the command, the cURL response contains the [obfuscated] PAT:

$ curl -u ibmuser:ibmpass -X POST https://zowe.gateway.net:1054/gateway/api/v1/auth/access-token/generate -d "{""validity"":90,""scopes"":[""ibmzosmf"",""bcmopsrestapiga""]}"
eyJhbGciOigawdszI1NiJ9.eyJagasdgasdgfasd23523423r0IjoxNzEwOTU1MjIxLCJleHAiOjE3MTg3MzEyMjEsImlzcyI6IkFQSU1MX1BBVCIsImp0aSI6ImUyYmFlMjQyLTRmZWItNGU3Yi05ZmNlLTYzYmU2Njg2MTM4YyIsImF1dGgucHJvdiI6IkFQSU1MIiwic2NvcGVzIjpbImJjbW9wc3Jlc3RhcGlnYSIsImlibXpvc21mIl19.QQFq_HhmgNFVnCm_MKxtOH5HyMX4QfRdU0PaqSveMcKUyDsXKoAcgLensRPmkrFQaKIuN80UX4iQsacwhpGbq-eSKVH7nW1P0QWqZVh8DF7Sx39kVgR8lU0Zt9M0CpyGucR1TcmVoHhEZtWZV1fn0_3J-eW0fetFuDUD7nLa49zBMH5s2z_BwOpj3FIEXPuI_V5CV7_IGDe9EA_QPpX1BCu9BVSzJAfHkD5NAPDrkFyaFSio6q9djbj-ug-XS9H5NbDBE1R5LRvbGMBjuOf8w6tRTTRMl2rJ3-J2OttaNLCo6jOY4Ytpe-MiYR3sdfsdfg5GFEUL83s52PtUwZ0Kg1NbUlA

The PAT is in JSON Web Token (JWT) format and contains readable info when decoded:

{
  "sub": "ibmuser",
  "iat": 1710955221,
  "exp": 1718731221,
  "iss": "APIML_PAT",
  "auth.prov": "APIML",
  "scopes": [
    "bcmopsrestapiga",
    "ibmzosmf"
  ]
}

Using a PAT

Next, we use the PAT to execute three different API service requests:

z/OSMF REST API
OPS/MVS REST API
NetMaster REST API

z/OSMF REST API — Get jobs

First, we’ll use cURL to list jobs on the system while providing the PAT as an Authorization header to list jobs on the system (note the PAT is intentionally truncated):

$ curl -X GET https://zowe.gateway.net:1024/ibmzosmf/api/v1/zosmf/restjobs/jobs -H "X-CSRF-ZOSMF-HEADER: true" -H "Authorization: Bearer eyJh..."

This gives a JSON response (formatted in VS Code):

OPS/MVS REST API — List Subsystems

Here, we’ll again use cURL with the same PAT to list OPS/MVS subsystems:

$ curl -X GET https://zowe.gateway.net:1024/bcmopsrestapiga/api/v1/subsystems -H "Authorization: Bearer eyJ..."

This also gives a JSON response:

OPS subsystems display from curl using a PAT

NetMaster REST API — List Regions

Lastly, we’ll use cURL to attempt to list the NetMaster regions:

$ curl -X GET https://zowe.gateway.net:1024/bcmnetmastermlmaster/api/v1/server/regions -H "Authorization: Bearer eyJ..."

However, this gives this response (formatted in VS Code):

NetMaster region display returns an error because the NetMaster service was not in “scopes”

Note that this error is expect since the scopes for the PAT itself did not include the NetMaster service ID: bcmnetmastermlmaster.

Using a PAT w/Zowe CLI

If you’re starting with a zowe.config.json that was generated via the zowe config auto-init, you obtain a PAT and can provide it to Zowe CLI via:

the --token-value command line parameter
the ZOWE_OPT_TOKEN_VALUE environmental variable

Here we use the--token-value CLI parameter providing our PAT to Zowe CLI and list jobs on our system:

$ zowe jobs list jobs --token-value eyJ...
TSU87548   IBMUSER ACTIVE

Since we see a TSO user returned in the response, we are able verify that we can list jobs on our mainframe system using a PAT obtained through the API ML. We can now store this token in our preferred CI/CD tooling so that Zowe CLI commands can operate on a mainframe system using a PAT.

Summary

The PAT allows you to grant access to only the services you need for a specific use case and can be easily stored in a credential manager for use with Zowe CLI in something like a Jenkins pipeline.

Although there is a currently an issue that prevents a PAT from working correctly in some cases, it will likely be resolved soon.

If you enjoyed this blog checkout more Zowe blogs here. Or, ask a question and join the conversation on the Open Mainframe Project Slack Channel #Zowe-help, #Zowe-announcements or #Zowe-onboarding. If this is your first time using the Open Mainframe slack channel register here.