API Authentication

Storm MCP has two types of APIs with different authentication methods:

ℹ️ Info

Important Distinction:

Management API (/api/v1/*) - For managing gateways, apps, and settings

Gateway Endpoints (/gateway/{id}/mcp) - For executing MCP tools

This guide covers the Management API. For gateway endpoints, see Gateway Endpoints & MCP Protocol.

Management API Authentication

The Storm MCP Management API supports multiple authentication methods to suit different use cases and security requirements.

Bearer Token (Recommended)

The preferred method for management API using Bearer tokens:

# ✅ CORRECT for Management API endpoints
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.stormmcp.ai/v1/gateways

⚠️ Warning

Gateway Endpoint Authentication is Different!

Gateway endpoints (/gateway/{id}/mcp) use X-API-Key header:

# ❌ WRONG for gateway endpoints - Returns 401 curl -H "Authorization: Bearer YOUR_API_KEY" \ https://stormmcp.ai/gateway/{id}/mcp # ✅ CORRECT for gateway endpoints curl -H "X-API-Key: YOUR_API_KEY" \ https://stormmcp.ai/gateway/{id}/mcp

See Gateway Endpoints Guide for details.

Example in JavaScript:

const response = await fetch("https://api.stormmcp.ai/v1/gateways", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
});

Example in Python:

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.stormmcp.ai/v1/gateways',
    headers=headers
)

Query Parameter

Less secure but useful for simple scripts:

curl "https://api.stormmcp.ai/v1/gateways?api_key=YOUR_API_KEY"

⚠️ Warning

Query parameter authentication exposes your API key in URLs and logs. Use only for testing or non-sensitive operations.

OAuth 2.0

For user-delegated access:

GET https://auth.stormmcp.ai/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=gateways:read apps:write
  &state=RANDOM_STATE

After authorization, exchange the code for an access token:

POST https://auth.stormmcp.ai/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=https://yourapp.com/callback

API Key Management

Generating API Keys

API keys can be generated through the web interface or API:

POST /api-keys
Authorization: Bearer EXISTING_API_KEY

{
  "name": "Production Server",
  "expires_at": "2025-12-31T23:59:59Z",
  "scopes": ["gateways:*", "apps:read"]
}

Response:

{
  "data": {
    "id": "key_abc123",
    "key": "sk_live_abc123xyz789...",
    "name": "Production Server",
    "created_at": "2025-01-28T10:30:45Z",
    "expires_at": "2025-12-31T23:59:59Z",
    "scopes": ["gateways:*", "apps:read"]
  }
}

ℹ️ Info

The API key is shown only once in the response. Store it securely immediately.

Key Rotation

Rotate keys regularly for security:

POST /api-keys/{key_id}/rotate
Authorization: Bearer CURRENT_API_KEY

{
  "grace_period_hours": 24
}

This creates a new key while keeping the old one active for the grace period.

Revoking Keys

Immediately invalidate a compromised key:

DELETE /api-keys/{key_id}
Authorization: Bearer ADMIN_API_KEY

Scopes and Permissions

Available Scopes

Control API key permissions with scopes:

Scope	Description
`*`	Full access (admin only)
`gateways:read`	View gateways
`gateways:write`	Create/update gateways
`gateways:delete`	Delete gateways
`apps:read`	View apps
`apps:write`	Connect/configure apps
`logs:read`	View logs and metrics
`sessions:manage`	Manage active sessions
`team:manage`	Manage team members
`billing:manage`	View and update billing

Scope Inheritance

Some scopes include others:

gateways:* includes:
  - gateways:read
  - gateways:write
  - gateways:delete

admin includes:
  - All scopes

Checking Permissions

Verify what permissions a key has:

GET /auth/verify
Authorization: Bearer YOUR_API_KEY

Response:

{
  "data": {
    "valid": true,
    "key_id": "key_abc123",
    "user_id": "user_xyz789",
    "scopes": ["gateways:read", "apps:read"],
    "expires_at": "2025-12-31T23:59:59Z"
  }
}

Service Accounts

For automated systems and CI/CD:

Creating Service Accounts

POST /service-accounts
Authorization: Bearer ADMIN_API_KEY

{
  "name": "CI/CD Pipeline",
  "description": "Automated deployment system",
  "scopes": ["gateways:write", "apps:read"]
}

Service Account Keys

Service accounts can have multiple keys:

POST /service-accounts/{account_id}/keys

{
  "name": "GitHub Actions Key",
  "expires_in_days": 90
}

JWT Authentication

For advanced use cases, JWT tokens are supported:

JWT Structure

{
  "header": {
    "alg": "RS256",
    "typ": "JWT",
    "kid": "key_id_123"
  },
  "payload": {
    "sub": "user_xyz789",
    "iat": 1706437845,
    "exp": 1706441445,
    "scopes": ["gateways:read", "apps:write"],
    "jti": "jwt_unique_id"
  }
}

Using JWTs

const jwt = generateJWT(privateKey, {
  sub: userId,
  scopes: ["gateways:read"],
  exp: Math.floor(Date.now() / 1000) + 3600,
});

fetch("https://api.stormmcp.ai/v1/gateways", {
  headers: {
    Authorization: `Bearer ${jwt}`,
  },
});

Multi-Factor Authentication

For enhanced security on sensitive operations:

Requiring MFA

Some endpoints require MFA verification:

DELETE /gateways/{gateway_id}
Authorization: Bearer YOUR_API_KEY
X-MFA-Token: 123456

MFA Challenge Flow

Attempt protected action:

DELETE /gateways/{gateway_id}
Authorization: Bearer YOUR_API_KEY

Receive MFA challenge:

{
  "error": {
    "code": "MFA_REQUIRED",
    "message": "Multi-factor authentication required",
    "challenge_id": "mfa_abc123"
  }
}

Submit MFA code:

POST /auth/mfa/verify
Authorization: Bearer YOUR_API_KEY

{
  "challenge_id": "mfa_abc123",
  "code": "123456"
}

Receive temporary token:

{
  "data": {
    "mfa_token": "mfa_token_xyz789",
    "expires_in": 300
  }
}

Retry with MFA token:

DELETE /gateways/{gateway_id}
Authorization: Bearer YOUR_API_KEY
X-MFA-Token: mfa_token_xyz789

IP Whitelisting

Restrict API access by IP address:

Configuring IP Restrictions

PATCH /account/security
Authorization: Bearer ADMIN_API_KEY

{
  "ip_whitelist": [
    "203.0.113.0/24",
    "198.51.100.5/32"
  ],
  "enforce_ip_whitelist": true
}

Bypass for Specific Keys

Create keys that bypass IP restrictions:

POST /api-keys

{
  "name": "Mobile App Key",
  "bypass_ip_whitelist": true,
  "scopes": ["gateways:read"]
}

Rate Limiting by Authentication

Different rate limits apply based on authentication:

Method	Requests/Hour	Burst
No Auth	60	10
API Key	1000	100
OAuth Token	1000	100
Service Account	5000	500
Enterprise	10000	1000

Security Best Practices

API Key Security

Never expose keys in code:

// Bad ❌
const apiKey = "sk_live_abc123...";

// Good ✅
const apiKey = process.env.STORM_API_KEY;

Rotate keys regularly:

# Automate key rotation
storm-mcp rotate-keys --schedule monthly

Use minimal scopes:

{
  "scopes": ["gateways:read"] // Only what's needed
}

Secure Storage

Store API keys securely:

Environment Variables - For applications
Secret Managers - AWS Secrets Manager, Vault
CI/CD Secrets - GitHub Secrets, Jenkins Credentials
Never in: Git, logs, URLs, client-side code

Monitoring Access

Track API key usage:

GET /api-keys/{key_id}/usage
Authorization: Bearer ADMIN_API_KEY

Response:

{
  "data": {
    "last_used": "2025-01-28T10:30:45Z",
    "last_ip": "203.0.113.45",
    "requests_today": 234,
    "requests_this_month": 5678
  }
}

Troubleshooting Authentication

Common Issues

401 Unauthorized:

Check API key is valid
Verify key hasn't expired
Ensure proper header format

403 Forbidden:

Check key has required scopes
Verify IP whitelist settings
Confirm resource permissions

429 Too Many Requests:

Check rate limit status
Consider upgrading plan
Implement exponential backoff

Debug Authentication

Test authentication and see details:

curl -v -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.stormmcp.ai/v1/auth/debug

API Authentication

Management API Authentication

Bearer Token (Recommended)

Query Parameter

OAuth 2.0

API Key Management

Generating API Keys

Key Rotation

Revoking Keys

Scopes and Permissions

Available Scopes

Scope Inheritance

Checking Permissions

Service Accounts

Creating Service Accounts

Service Account Keys

JWT Authentication

JWT Structure

Using JWTs

Multi-Factor Authentication

Requiring MFA

MFA Challenge Flow

IP Whitelisting

Configuring IP Restrictions

Bypass for Specific Keys

Rate Limiting by Authentication

Security Best Practices

API Key Security

Secure Storage

Monitoring Access

Troubleshooting Authentication

Common Issues

Debug Authentication

Next Steps