Authentication

Authentication

All API requests require authentication. myumbrella.ai supports two authentication methods: API keys for server-to-server calls and OAuth 2.0 for user-facing integrations.

API Keys

Generate API keys in Settings → API Keys. Each key is scoped to specific permissions.

Include your API key in the Authorization header:

curl -X GET https://api.myumbrella.ai/v1/plans \
  -H "Authorization: Bearer mu_live_abc123def456" \
  -H "Content-Type: application/json"

Key Types

Type	Prefix	Use Case
Live	mu_live_	Production API calls
Test	mu_test_	Sandbox testing (no real charges)

OAuth 2.0

For apps that act on behalf of merchants, use the OAuth flow:

1. Redirect the merchant to:

   https://app.myumbrella.ai/oauth/authorize?client_id=YOUR_ID&redirect_uri=YOUR_URI&scope=plans:read+claims:write

2. After authorization, exchange the code for an access token:

   curl -X POST https://api.myumbrella.ai/oauth/token \
     -d "grant_type=authorization_code" \
     -d "code=AUTH_CODE" \
     -d "client_id=YOUR_ID" \
     -d "client_secret=YOUR_SECRET"

Rate Limits

• Live keys: 1,000 requests/minute
• Test keys: 100 requests/minute
• Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Error Responses

Authentication failures return a 401 status:

{
  "error": "unauthorized",
  "message": "Invalid or expired API key"
}