Authentication

Claw GRC supports two authentication methods: Firebase JWT tokens for human users and API keys for agents. All API requests must include one of these authentication credentials.

Base URL

https://api.clawgrc.com

All API endpoints are prefixed with /api/v1/.

Firebase JWT (Human Users)

Human users authenticate through Firebase Authentication. After signing in through the web application or Firebase SDK, you receive a JWT token that is included in the Authorization header.

Obtaining a Token

import { getAuth, signInWithEmailAndPassword } from 'firebase/auth';

const auth = getAuth();
const userCredential = await signInWithEmailAndPassword(auth, email, password);
const token = await userCredential.user.getIdToken();

Using the Token

curl https://api.clawgrc.com/api/v1/frameworks \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Token Validation

The API Gateway validates JWT tokens by:

1. Fetching Google's public keys for Firebase token verification
2. Verifying the token signature, expiration, and audience
3. Extracting the user's organization ID and role from custom claims
4. Setting internal headers (X-Org-ID, X-Actor-ID, X-Actor-Type, X-Actor-Role) for downstream services

Token Refresh

Firebase tokens expire after 1 hour. The Firebase SDK handles automatic refresh. If using the REST API directly, call the token refresh endpoint:

curl -X POST https://securetoken.googleapis.com/v1/token?key=YOUR_FIREBASE_API_KEY \
  -d 'grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN'

API Keys (Agents)

AI agents authenticate using API keys prefixed with cgrc_. API keys are issued when an agent is registered and can be rotated without re-registering the agent.

Using an API Key

curl https://api.clawgrc.com/api/v1/mcp/tools \
  -H "X-API-Key: cgrc_ABCDEFghijklmnopqrstuvwxyz1234567890ABCD"

Key Format

API keys follow the format: cgrc_ + 43 characters of URL-safe base64.

cgrc_ABCDEFghijklmnopqrstuvwxyz1234567890ABCD
^     ^
|     +-- 43 chars of cryptographic randomness
+-- prefix for identification

Key Storage

API keys are stored as SHA-256 hashes in the database. The plaintext key is returned only once, at registration time. If lost, the key must be rotated using the key rotation endpoint.

Key Rotation

POST /api/v1/agents/{agent_id}/rotate-key
Authorization: Bearer YOUR_JWT_TOKEN

This generates a new key, invalidates the old one, and returns the new plaintext key. The rotation is logged in the audit trail.

Request Headers

Required Headers

Header	Auth Type	Description
Authorization: Bearer <token>	JWT	Firebase JWT token for human users
X-API-Key: <key>	API Key	Agent API key
Content-Type: application/json	Both	Required for POST/PUT requests

Internal Headers (Set by API Gateway)

These headers are set by the API Gateway after authentication. They are stripped from incoming requests to prevent spoofing and cannot be set by clients:

Header	Description
X-Org-ID	Organization UUID for tenant isolation
X-Actor-ID	User UUID or agent UUID
X-Actor-Type	user or agent
X-Actor-Role	owner, admin, auditor, or developer
X-Actor-Email	User's email address (JWT only)
X-Gateway-Secret	Shared secret proving the request came from the gateway

:::warning Security Note The API Gateway strips all X-Org-ID, X-Actor-ID, X-Actor-Type, X-Actor-Role, and X-Actor-Email headers from incoming requests before setting them from the authenticated context. This prevents header injection attacks where a malicious client could forge an organization ID to access another tenant's data. :::

Development Mode

When the API Gateway is running with ENVIRONMENT=development, authentication is bypassed. All requests are treated as authenticated with a default development identity. This is intended for local development only and is never enabled in production.

Rate Limiting

API requests are rate-limited per organization:

Plan	Requests per Minute	Burst
Free	60	10
Starter	300	50
Professional	1,000	100
Enterprise	5,000	500

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1705312800

When rate limited, the API returns 429 Too Many Requests.

Circuit Breaker

The API Gateway implements circuit breakers for each downstream service (compliance engine, security engine, agent protocol). If a service is experiencing failures, the circuit breaker will temporarily reject requests to that service with a 503 Service Unavailable response rather than queuing requests that will likely fail.

The circuit breaker opens after 5 consecutive failures and enters a half-open state after 30 seconds, allowing a single request through to test recovery.