Three Gates
Three Gates Developer Docs

Authentication Best Practices

Protect your Three Gates 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 Three Gates credentials out of version control.

bash
# .env.local\nTHREEGATES_API_KEY=tgk_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 Three Gates 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 Three Gates CLI.

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

3. Security Checklist

  • Use HTTPS for every request. Three Gates rejects plaintext HTTP.
  • Never commit API keys to Git repositories or share them via chat.
  • Call Three Gates 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

Three Gates 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}