Docs/Authentication

Authentication

Guardrail.ai uses API key-based authentication. Every request must include a valid API key in the Authorization header.

How It Works

When you generate an API key, we compute its SHA-256 hash and store only the hash — never the plaintext key. On each request, we hash your Bearer token and compare it in constant time to prevent timing attacks. Your key cannot be recovered from our database even in a breach scenario.

⚠️ Your full API key is shown once — at generation time. Copy it to a secret manager (1Password, AWS Secrets Manager, Doppler, etc.) immediately. We cannot recover it for you.

Bearer Token Format

Include your key in every HTTP request using the standard Bearer scheme:

header

Authorization: Bearer sk_your_api_key_here

curl

curl -X POST https://api.guardrail.ai/v1/guardrail/check \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "my-agent", "proposed_text": "Hello world"}'

Key Prefix Format

All Guardrail API keys begin with the sk_ prefix followed by a 26-character random alphanumeric string.

sk_8r8zo7ec09rqrwa3u0x37

Security Best Practices

Never embed keys in client-side code

API calls revealing your key in browser JavaScript, mobile apps, or Git repositories are a critical vulnerability. Always proxy through a backend service.

Use environment variables

Store your key as GUARDRAIL_API_KEY in your environment or secrets manager. Never hardcode it in source files.

Rotate keys regularly

Generate a new key from the dashboard every 90 days. Old keys can be revoked instantly via the API Keys panel.

One key per service

Generate a separate key for each agent or service. This limits blast radius if a key is compromised and provides clean audit trails.

Authentication Errors

HTTP Code	Reason
401 Unauthorized	No Authorization header, invalid key format, or key not found in the database.
401 Unauthorized	Key has been manually revoked via the dashboard.
402 Payment Required	Key is valid but the account has zero credits remaining.