Azure APIM Subscription Key Management

Azure Platform Universal Feature

This guide applies to all WorkMax, LLC API products deployed through Azure API Management (APIM). Subscription keys are required for authenticating API requests to the Azure APIM gateway.

Overview

Azure API Management (APIM) uses subscription keys to control access to API products. Every API request to WorkMax, LLC products deployed in Azure APIM must include a valid subscription key in the request headers.

WorkMax APIM Portal:

https://workmax.developer.azure-api.net

What is a Subscription Key?

A subscription key is a unique identifier that:

Authenticates your application to the Azure APIM gateway
Associates API usage with your account
Enables rate limiting and quota enforcement
Allows WorkMax to track usage and provide analytics

Subscription keys are NOT the same as:

OAuth access tokens (used for user authentication)
API keys from other services
Azure AD credentials

Key Concepts

Products

A product in Azure APIM is a bundle of one or more APIs. Each product has its own subscription keys.

Example WorkMax Products:

WorkMax Platform APIs
WorkMax APIs
TheEdge APIs
P4C APIs

Primary vs. Secondary Keys

Each subscription provides two keys:

Primary Key - Your main key for API requests
Secondary Key - Backup key for rotation scenarios

Why Two Keys?

Two keys allow you to rotate keys without downtime. You can regenerate the primary key while your application uses the secondary key, then update your application to use the new primary key.

Subscription Scopes

Subscriptions can be scoped to:

Product - Access to all APIs in a product (most common)
API - Access to a specific API only
All APIs - Access to all APIs in the APIM instance (admin only)

Getting Your First Subscription Key

Prerequisites

✅ Azure AD B2C account with WorkMax, LLC
✅ MFA configured (required for portal access)
✅ Access to email associated with your account

Navigate to https://workmax.developer.azure-api.net/signup
If not logged in, you will be redirected to Azure AD B2C login
- Enter your email and password
- Complete MFA verification
On the Sign Up page:
- First Name - Enter your first name
- Last Name - Enter your last name
- Email - Pre-filled with your Azure AD account email
- Click [Sign up]
Check your email for a confirmation message

Subject: "Welcome to WorkMax Developer Portal"
Click the confirmation link

✅ Your account is now activated
Navigate to https://workmax.developer.azure-api.net/products
Select the product you want to subscribe to

Example: "WorkMax Platform APIs"

Click [Subscribe]
In the Subscription name field:
- Enter a descriptive name (e.g., "MyCompany Integration - Dev")
- Click [Subscribe]
✅ Your subscription is created
- Primary and Secondary keys are displayed
- Copy and save both keys securely

Save Your Keys Securely

Store keys in a secure location (password manager, secrets vault)
Never commit keys to source control (Git, SVN, etc.)
Treat keys like passwords - do not share publicly

Using Subscription Keys in API Requests

HTTP Header Method (Recommended)

Include your subscription key in the Ocp-Apim-Subscription-Key header:

bash

curl -X GET "https://api-sandbox.workmax.com/workmax/v1/costcodes" \
  -H "Authorization: Bearer {yourOAuthToken}" \
  -H "Ocp-Apim-Subscription-Key: {yourSubscriptionKey}" \
  -H "Content-Type: application/json"

Query Parameter Method (Not Recommended)

Include your subscription key as a query parameter:

bash

curl -X GET "https://api-sandbox.workmax.com/workmax/v1/costcodes?subscription-key={yourSubscriptionKey}" \
  -H "Authorization: Bearer {yourOAuthToken}" \
  -H "Content-Type: application/json"

Query Parameter Security Risk

Using subscription keys in query parameters exposes them in:

Server logs
Browser history
Proxy server logs
Analytics tools

Always use the HTTP header method in production.

Managing Your Subscriptions

View All Subscriptions

Log in to https://workmax.developer.azure-api.net
Click your username in the top-right corner
Select [Profile] from the dropdown
Click [Subscriptions] in the left menu
✅ All your subscriptions are listed with:
- Subscription name
- Product name
- Status (Active / Suspended / Cancelled)
- Primary and Secondary keys (hidden by default)

Show/Hide Subscription Keys

On the Subscriptions page, locate the subscription
Click [Show] next to Primary key or Secondary key
The key is displayed temporarily
Click the copy icon to copy to clipboard

Security Feature

Keys are hidden by default and require you to explicitly show them. This prevents shoulder surfing and accidental exposure.

Rename a Subscription

On the Subscriptions page, locate the subscription
Click [...] (three dots) next to the subscription name
Select [Rename]
Enter a new name and click [Save]

Key Rotation Best Practices

Key rotation is the process of replacing old subscription keys with new ones to maintain security.

When to Rotate Keys:

✅ Every 90 days (recommended security practice)
✅ When a key is compromised or exposed
✅ When a team member with key access leaves
✅ After a security audit or incident
✅ Before moving from development to production

Zero-Downtime Key Rotation Process

Use Secondary Key for Seamless Rotation

Azure APIM provides two keys specifically to enable rotation without API downtime.

Step 1: Switch Application to Secondary Key

Update your application configuration to use the Secondary Key instead of Primary Key
Deploy the configuration change to all environments
Verify API requests work with Secondary Key
Monitor for 24-48 hours to ensure no issues

Step 2: Regenerate Primary Key

Log in to https://workmax.developer.azure-api.net
Navigate to Profile > Subscriptions
Locate the subscription and click [...] (three dots)
Select [Regenerate primary key]
Confirm the regeneration
- ⚠️ Old primary key stops working immediately
Copy the new Primary Key

Step 3: Update Application to New Primary Key

Update your application configuration to use the new Primary Key
Deploy the configuration change
Verify API requests work with new Primary Key
✅ Primary key rotation complete

Step 4: Regenerate Secondary Key (Optional)

Repeat Step 2 process for Secondary Key
This ensures both keys are fresh
✅ Full key rotation complete

Regenerating Keys

Regenerate Primary Key

Navigate to Profile > Subscriptions
Click [...] next to the subscription
Select [Regenerate primary key]
In the confirmation dialog:
- ⚠️ Warning: "This will invalidate the current primary key immediately"
- Click [Regenerate]
✅ New primary key is generated and displayed
Copy the new key and update your application configuration

Regenerate Secondary Key

Follow the same process but select [Regenerate secondary key]

Key Regeneration is Immediate

When you regenerate a key, the old key stops working immediately. Ensure you update all applications using the old key before regeneration, or use the zero-downtime rotation process described above.

Managing Multiple Product Subscriptions

If you integrate with multiple WorkMax, LLC products (e.g., WorkMax Platform AND WorkMax), you will need separate subscriptions for each product.

Best Practices for Multiple Subscriptions

Naming Convention:

{CompanyName}-{ProductName}-{Environment}
Examples:
- Acme-WorkMaxPlatform-Dev
- Acme-WorkMaxPlatform-Prod
- Acme-WorkMax-Dev
- Acme-WorkMax-Prod

Configuration Management:

javascript

// config.js
const config = {
  workmaxPlatform: {
    dev: {
      apiUrl: 'https://api-sandbox.workmax.com',
      subscriptionKey: process.env.WORKMAX_DEV_SUBSCRIPTION_KEY
    },
    prod: {
      apiUrl: 'https://api.workmax.com',
      subscriptionKey: process.env.WORKMAX_PROD_SUBSCRIPTION_KEY
    }
  },
  workmax: {
    dev: {
      apiUrl: 'https://api-workmax-sandbox.workmax.com',
      subscriptionKey: process.env.WORKMAX_DEV_SUBSCRIPTION_KEY
    },
    prod: {
      apiUrl: 'https://api-workmax.workmax.com',
      subscriptionKey: process.env.WORKMAX_PROD_SUBSCRIPTION_KEY
    }
  }
};

Subscription Status

Active

✅ Subscription is operational
API requests are accepted
Rate limits and quotas are enforced

Suspended

⚠️ Subscription is temporarily disabled
API requests return 401 Unauthorized
Common Reasons:
- Payment issues (if applicable)
- Rate limit violations
- Terms of service violations
- Manual suspension by administrator

To Reactivate:

Contact API-Services@workmax.com
Resolve the underlying issue
Request reactivation

Cancelled

❌ Subscription is permanently disabled
API requests return 401 Unauthorized
Cannot be reactivated (must create new subscription)

Error Responses

401 Unauthorized - Missing Subscription Key

json

{
  "statusCode": 401,
  "message": "Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API."
}

Solution:

Add Ocp-Apim-Subscription-Key header to your request
Verify the header name is spelled correctly

401 Unauthorized - Invalid Subscription Key

json

{
  "statusCode": 401,
  "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
}

Solution:

Verify you copied the complete key (no extra spaces or characters)
Check if the key was regenerated
Verify subscription is Active (not Suspended or Cancelled)
Confirm you're using the correct product subscription

403 Forbidden - Subscription Not Authorized for API

json

{
  "statusCode": 403,
  "message": "Subscription does not have access to this API. Please subscribe to the product that includes this API."
}

Solution:

Verify you're subscribed to the correct product
Check if the API is included in your product subscription
Subscribe to the correct product

Security Best Practices

✅ DO:

Store keys in environment variables or secure vaults (Azure Key Vault, AWS Secrets Manager)
Use separate keys for each environment (dev, staging, production)
Rotate keys every 90 days
Use HTTP header method for passing subscription keys
Monitor key usage through APIM analytics
Revoke keys immediately if compromised
Use HTTPS only for API requests

❌ DON'T:

Don't commit keys to source control (add to .gitignore)
Don't share keys publicly (Slack, email, forums, documentation)
Don't use the same key for dev and production
Don't pass keys in query parameters (logged in URLs)
Don't embed keys in client-side code (JavaScript, mobile apps)
Don't use production keys for testing

Troubleshooting

"I can't find my subscription keys"

Log in to https://workmax.developer.azure-api.net
Navigate to Profile > Subscriptions
Click [Show] next to the key you need
If no subscriptions exist, you need to subscribe to a product first

"My subscription key doesn't work"

Checklist:

✅ Key is copied completely without extra spaces
✅ Using correct header name: Ocp-Apim-Subscription-Key
✅ Subscription status is Active (not Suspended/Cancelled)
✅ Subscribed to correct product for the API you're calling
✅ Using HTTPS (not HTTP)
✅ Key hasn't been recently regenerated

"How do I delete a subscription?"

Currently, subscription deletion must be requested through WorkMax support:

Email: API-Services@workmax.com
Include: Subscription name and reason for deletion

Integration Onboarding - Access and credentials
FAQ - Common questions
WorkMax API Reference - Resource-level reference

Support

Need help with subscription keys?

Email: API-Services@workmax.com
APIM Portal: https://workmax.developer.azure-api.net

Include in your support request:

Your account email
Subscription name (if applicable)
Product you're trying to access
Complete error message
Steps to reproduce the issue

Azure APIM Subscription Key Management ​

Overview ​

What is a Subscription Key? ​

Key Concepts ​

Products ​

Primary vs. Secondary Keys ​

Subscription Scopes ​

Getting Your First Subscription Key ​

Prerequisites ​

Sign Up Steps ​

Using Subscription Keys in API Requests ​

HTTP Header Method (Recommended) ​

Query Parameter Method (Not Recommended) ​

Managing Your Subscriptions ​

View All Subscriptions ​

Show/Hide Subscription Keys ​

Rename a Subscription ​

Key Rotation Best Practices ​

Zero-Downtime Key Rotation Process ​

Regenerating Keys ​

Regenerate Primary Key ​

Regenerate Secondary Key ​

Managing Multiple Product Subscriptions ​

Best Practices for Multiple Subscriptions ​

Subscription Status ​

Active ​

Suspended ​

Cancelled ​

Error Responses ​

401 Unauthorized - Missing Subscription Key ​

401 Unauthorized - Invalid Subscription Key ​

403 Forbidden - Subscription Not Authorized for API ​

Security Best Practices ​

✅ DO: ​

❌ DON'T: ​

Troubleshooting ​

"I can't find my subscription keys" ​

"My subscription key doesn't work" ​

"How do I delete a subscription?" ​

Related Documentation ​

Support ​

Azure APIM Subscription Key Management

Overview

What is a Subscription Key?

Key Concepts

Products

Primary vs. Secondary Keys

Subscription Scopes

Getting Your First Subscription Key

Prerequisites

Sign Up Steps

Using Subscription Keys in API Requests

HTTP Header Method (Recommended)

Query Parameter Method (Not Recommended)

Managing Your Subscriptions

View All Subscriptions

Show/Hide Subscription Keys

Rename a Subscription

Key Rotation Best Practices

Zero-Downtime Key Rotation Process

Regenerating Keys

Regenerate Primary Key

Regenerate Secondary Key

Managing Multiple Product Subscriptions

Best Practices for Multiple Subscriptions

Subscription Status

Active

Suspended

Cancelled

Error Responses

401 Unauthorized - Missing Subscription Key

401 Unauthorized - Invalid Subscription Key

403 Forbidden - Subscription Not Authorized for API

Security Best Practices

✅ DO:

❌ DON'T:

Troubleshooting

"I can't find my subscription keys"

"My subscription key doesn't work"

"How do I delete a subscription?"

Related Documentation

Support