Authentication Troubleshooting

Common Issues

401 Unauthorized

Problem: API key authentication failed.

Possible causes:

1. API key is missing or incorrectly formatted
2. Key has expired
3. Key has been revoked
4. Incorrect header format

Solutions:

1. Check header format:

# Correct format
Authorization: Key your-api-key-here

# Common mistakes
Authorization: Bearer your-api-key-here  # Wrong
apikey: your-api-key-here               # Wrong
Key: your-api-key-here                  # Wrong

2. Verify key is not expired:

# Option 1: Check user info (key validation)
curl -H "Authorization: Key YOUR_KEY" \
  http://your-tobealert.com:9000/api/user/me

# Option 2: Get specific key info
curl -H "Authorization: Key YOUR_KEY" \
  http://your-tobealert.com:9000/api/key/YOUR_KEY_ID

# Note: API keys don't have explicit expiration in the response
# Key expiration is handled by the system internally

3. Test with a new key:
   • Create a fresh API key
   • Test with the new key
   • If it works, the old key may be revoked

403 Forbidden

Problem: API key doesn't have required permissions or license issue.

License-related causes:

1. License validation failed
2. License integrity check failed
3. Feature not enabled in license
4. License expired

Permission-related causes:

1. Key lacks required scope
2. User role insufficient

Solutions:

1. Check license status:

# Option 1: Validate license (POST)
curl -X POST -H "Content-Type: application/json" \
  http://your-tobealert.com:9000/api/license/validate

# Option 2: Get license details (GET, requires admin)
curl -H "Authorization: Key YOUR_KEY" \
  http://your-tobealert.com:9000/api/license/details

# Option 3: Check user info (includes roles and permissions)
curl -H "Authorization: Key YOUR_KEY" \
  http://your-tobealert.com:9000/api/user/me

2. Check what permissions the key has:

# Option 1: Check user info (includes roles and scopes)
curl -H "Authorization: Key YOUR_KEY" \
  http://your-tobealert.com:9000/api/user/me

# Option 2: List API keys (write:keys = your keys; admin = all keys)
curl -H "Authorization: Key YOUR_KEY" \
  http://your-tobealert.com:9000/api/keys

# Option 3: Get specific key info (write:keys for your key; admin for any)
curl -H "Authorization: Key YOUR_KEY" \
  http://your-tobealert.com:9000/api/key/YOUR_KEY_ID

3. Ensure the key has required permissions:
   • write:alerts for sending alerts
   • write:webhooks for creating webhooks
   • write:keys to manage your API keys; global admin to see all keys and assign Owner (same as Users and Groups)

API Key Not Working in Code

Problem: API key works with curl but not in your application.

Common issues:

1. Encoding problems:

# Wrong - key might be URL encoded
headers = {"Authorization": f"Key {quote(api_key)}"}

# Correct - use raw key
headers = {"Authorization": f"Key {api_key}"}

2. Trailing spaces or newlines:

# Clean the key
api_key = api_key.strip()

3. Environment variable issues:

# Check if variable is set
echo $API_KEY

# In Python, check if loaded
import os
api_key = os.getenv('API_KEY')
if not api_key:
    raise ValueError("API_KEY not set")

Backend Error Responses

Based on the backend implementation, here are the actual error responses:

License Errors (403)

1. License integrity check failed:

{
  "status": "error",
  "message": "integrity check failed",
  "code": 403,
  "errors": null,
  "requestId": "uuid-here"
}

2. License validation failed:

{
  "status": "error",
  "message": "License validation failed",
  "code": 403,
  "errors": null,
  "requestId": "uuid-here"
}

3. Invalid or expired license:

{
  "status": "error",
  "message": "Invalid or expired license",
  "code": 403,
  "errors": null,
  "requestId": "uuid-here"
}

4. All files are pristine (when integrity check passes):

{
  "status": "error",
  "message": "all files are pristine",
  "code": 403,
  "errors": null,
  "requestId": "uuid-here"
}

Authentication Errors (401)

1. Invalid API key:

{
  "status": "error",
  "message": "API key parameter 'invalid-key' is invalid",
  "code": 401,
  "errors": null,
  "requestId": "uuid-here"
}

2. Missing authorization:

{
  "status": "error",
  "message": "Missing authorization API Key or Bearer Token",
  "code": 401,
  "errors": null,
  "requestId": "uuid-here"
}

Permission Errors (403)

1. Missing required scope:

{
  "status": "error",
  "message": "Missing required scope: write:alerts",
  "code": 403,
  "errors": null,
  "requestId": "uuid-here"
}

Getting Help

1. Check the exact error message - Look at the full response body including requestId
2. Verify the URL - Ensure you're using the correct endpoint
3. Test with curl - Eliminate client-side issues
4. Check system time - Ensure your system clock is correct
5. Contact your administrator - If you need permissions or license issues

Emergency Procedures

If All Keys Fail

1. Contact your ToBeAlert administrator immediately
2. Check license status - The problem might be license-related
3. Use the web UI to create a new key if you have UI access
4. Check for system-wide outages - The problem might not be your key

If Key is Compromised

1. Immediately revoke the compromised key:

curl -X DELETE -H "Authorization: Key ADMIN_KEY" \
  http://your-tobealert.com:9000/api/key/COMPROMISED_KEY_ID

2. Create a new key with different permissions
3. Update all applications using the old key
4. Review audit logs to see what was accessed with the compromised key