Guardian Health LogoGuardian Health
AI Compliance Platform Developer Docs

Authentication Best Practices

Protect your Guardian Health API keys, implement secure rotation strategies, and gracefully handle authentication-related errors.

1. API Key Management

  • Store keys in environment variables or dedicated secrets managers—never hard-code them into source files.
  • Restrict access to production keys through role-based access controls and audit logging.
  • Use unique keys per environment (development, staging, production) to limit blast radius.

Using environment variables

Keep Guardian Health credentials out of version control.

bash
# .env.local\nGUARDIAN_API_KEY=ghp_live_XXXXXXXXXXXXXXXXXXXXXXXX

Many teams rely on services such as AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, or 1Password Secrets Automation for centralized key storage.

2. Key Rotation

Regular rotation minimizes risk if a key is exposed. Generate a new key, deploy it, and revoke the old key only after confirming that your applications are using the replacement.

  1. Create a secondary key in the Guardian Health dashboard.
  2. Update your secret manager or deployment configuration to use the new key.
  3. Monitor authentication metrics for errors before revoking the old key.

Zero-downtime rotation script

Example workflow using Azure Key Vault, Kubernetes, and the Guardian Health CLI.

bash
# Rotate keys without downtime\nCURRENT_KEY=$(az keyvault secret show --name guardian-primary --vault-name org-secrets --query value -o tsv)\nNEW_KEY=$(guardian keys create --label="prod-rotation-2024-11")\naz keyvault secret set --name guardian-secondary --vault-name org-secrets --value "$NEW_KEY"\nkubectl set env deployment/api GUARDIAN_API_KEY=$NEW_KEY\n# Monitor traffic, then remove the old key\nguardian keys revoke --key "$CURRENT_KEY"

3. Security Checklist

  • Use HTTPS for every request—Guardian Health rejects plaintext HTTP.
  • Never commit API keys to Git repositories or share them via chat.
  • Call Guardian Health from trusted server-side environments only.
  • Monitor key usage for anomalies such as spikes or access from unexpected IPs.

4. Common Authentication Errors

401 Unauthorized

Occurs when the API key is missing, malformed, or revoked. Verify the Authorization header and confirm the key is active.

403 Forbidden

Your key lacks access to the requested resource or environment. Confirm that the workspace permissions include the necessary scopes.

429 Too Many Requests

Guardian Health enforces rate limits. Implement exponential backoff and respect the Retry-After header before retrying.

Retry helper

Gracefully handle throttling with exponential backoff.

javascript
import fetch from "node-fetch";\n\nasync function getWithBackoff(url, options = {}, attempt = 1) {\n  try {\n    const response = await fetch(url, options);\n    if (response.status === 429 && attempt < 5) {\n      const retryAfter = Number(response.headers.get("retry-after")) || Math.pow(2, attempt);\n      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));\n      return getWithBackoff(url, options, attempt + 1);\n    }\n    if (!response.ok) throw new Error(`Request failed: ${response.status}`);\n    return response.json();\n  } catch (error) {\n    if (attempt < 5) {\n      await new Promise((resolve) => setTimeout(resolve, Math.pow(2, attempt) * 1000));\n      return getWithBackoff(url, options, attempt + 1);\n    }\n    throw error;\n  }\n}