StepZen CLI Modernized: Login with MCSP instanceId + apiKey (JWT-Based Authentication)

StepZen has introduced a more secure and collaborative authentication workflow for its CLI—powered by MCSP’s user management and API key model. This modern approach replaces the need for StepZen’s legacy AdminKey and brings a cloud-native way of managing user access.

This blog covers:

• Why the old AdminKey approach was limiting

• How MCSP user management works behind the scenes

• How to generate an API key in the IBM SaaS Console

• How StepZen CLI uses the new authentication architecture

• How to log in using the new instanceId + apiKey

• Backward compatibility with the legacy login

• Why JWT-based auth is a big improvement

Legacy Login: Functional but Limited

Previously, stepzen login required:  Domain, Environment name and AdminKey

The AdminKey was visible only to the service owner, making it difficult to collaborate with other developers. Everyone had to use the same AdminKey, which:

• Provided no user-level access control

• Made auditing impossible

• Exposed risk if the key leaked

• Forced painful credential rotation

The classic login still works for backwards compatibility, but StepZen recommends migrating to MCSP-based authentication.

👥 StepZen Adopts MCSP User Management

StepZen now uses IBM’s MCSP user management system.
This brings:

• Per-user API keys

• Role-based access

• Instance-level sharing

• Safe collaboration without exposing AdminKey

• Enhanced audit logs

Instance owners can now share their StepZen instance with users (Service users, APICGQL developers, etc.), and those users can generate their own API keys.

🔑 Introducing the New Login Model: instanceId + apiKey → JWT Token

The StepZen CLI now supports login using:

• Instance ID

• API Key 

The CLI exchanges these for a JWT token, which expires and auto-refreshes securely.

Example:

stepzen login --domain <domain> -i <instanceId> -k <apiKey>

This removes the need to expose AdminKey or environment details.

 How to Generate an API Key in the MCSP (IBM SaaS) Console

Before logging into StepZen CLI using JWT-based authentication, you must generate an API key from the IBM SaaS Console.

🔒 Required Roles

You must have one of these roles to access IBM API Connect for GraphQL (StepZen):

• Service owner

• Service admin

• Service user

• APICGQL administrator

• APICGQL developer

To create an API key, you must have at least:

• Service admin, or

• Service user role

🧰 Steps to Create an API Key

Follow these steps in the IBM SaaS Console:

1. Open Subscriptions

Go to the Subscriptions page in the IBM SaaS Console.

2. Locate Your Subscription

Find the subscription where your StepZen (APICGQL) instance exists, and click View instances.

3. Select the Instance

On the Instances tab, click the row of the StepZen instance you want to generate the key for.

4. Open API Keys Tab

Inside the instance view, go to the API Keys tab.

5. Click Generate Key

Press Generate key → A popup window appears.

6. Configure the API Key

Inside the Generate API key dialog:

• Select a Service ID

• Enter an API key name

• Add a description (optional)

• Select an expiration date (recommended but optional)

7. Generate the API Key

Click Generate key → A new API key is created.

8. Copy the API Key

You will see:

You have a limited time to copy the API key. It cannot be recovered later.

Click Copy to clipboard and store it securely.

If lost, you must generate a new key.

9. Key is Visible in Console

After closing the popup, the new API key appears inside the API Keys table.

🔁 Updating Access

API keys inherit access from the Service ID or user they are associated with.

If you update permissions for that user/service ID, the API key automatically follows those permissions across instances and accounts.

🧭 Logging In Using the Newly Created API Key

Now that you have:

• apiKey (from the steps above)

• instanceId (visible in the StepZen dashboard)

• domain (visible in StepZen dashboard)

…you can log in using:

stepzen login <domain> -i <instance_id> -k <apiKey>

Example:

stepzen login apis.stepzen.com -i 1234abcd5678 -k mcp_xxx_yyy_zzz

StepZen will:

• Exchange your API key for a short-lived JWT

• Store the JWT in StepZen’s CLI config

• Use the JWT for all future API / deploy operations

⚙️ Using CLI Commands After JWT Login

Once you log in using the new MCSP API key + instance ID, all StepZen CLI commands continue to work exactly as before — but now they use a JWT access token instead of the legacy AdminKey.

Common Commands

Deploy a GraphQL API or schema to the API Connect for GraphQL server.

stepzen deploy [<endpoint>] [--config=<config>] [--dir=<dir>]

Check the current logged-in user

> stepzen whoami

Account: public3***9b 
Domain: us-east-a.ibm.steprz.net 
Instance Id: 20250320-0847-3668-7006-2138aaf65231 
Email: sh232.k.m@xyz.com 
Access Token: ************************

View the active JWT access token

> stepzen whoami --accesstoken

This displays the JWT currently being used by the CLI for authentication.

All commands now authenticate using the JWT generated from your MCSP API key, ensuring secure, user-specific access instead of the shared AdminKey.

🔄 How JWT Auth Works Internally

1. CLI sends instanceId + apiKey to MCSP auth endpoint

2. MCSP validates your permissions

3. MCSP issues a JWT token

4. CLI stores this token

5. All StepZen commands (deploy, list, start, whoami) use JWT

6. When the JWT expires, CLI ask to re-login

This entire workflow is secure, modern, and cloud-native.

🏛 Legacy AdminKey Login Still Supported

To avoid breaking existing workflows, StepZen still supports the legacy login:

stepzen login -a <account_name> -k <adminKey>

But remember:

• AdminKey visibility is restricted to the service owner

• It’s not recommended for collaborative environments

• It lacks user-level access control

The future is MCSP-based login.

🎯 Why This Upgrade Matters

✔ Secure

Per-user API keys remove shared secrets.

✔ Collaborative

Service owners can share instances with any team member.

✔ Traceable

JWT-based auth enables user-level audit logs.

✔ Compatible

Legacy login still supported.

✔ Cloud-Native

Matches IAM patterns used in AWS, GCP, Azure.