Skip to main content
All ChainGuard API requests require authentication using API keys.

​
API Key Format

ChainGuard API keys follow this format: 
cg_<environment>_<32_character_string>

Examples:
cg_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
cg_test_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4
  • cg_live_: Production. Use this for real security data.
  • cg_test_: Sandbox. Use this for testing and development.

​
Obtaining API Keys

1

Create Account

Sign up at dashboard.chainguardai.dev
2

Navigate to API Keys

Go to Settings → API Keys → Create New Key
3

Configure Permissions

Select the required scopes for your use case
4

Store Securely

Copy your API key immediately. It will only be shown once.
API keys are shown only once upon creation. Store them securely. If lost, revoke and create a new key.

​
Using API Keys

Include the API key in the Authorization header: 
curl --request GET \
  --url https://api.chainguardai.dev/v1/risk/score/0x742d35Cc6634C0532925a3b844Bc454c459dFE2C \
  --header 'Authorization: Bearer cg_live_xxxxxxxxxxxxxxxx'
For testing only. Not secure for production: 
curl --request GET \
  --url 'https://api.chainguardai.dev/v1/risk/score/0x...?api_key=cg_live_xxxxxxxx'

​
Scopes

API keys can be scoped to specific permissions:
  • scan:read: URL and contract scanning. Endpoints: /scan/*.
  • risk:read: Risk score retrieval. Endpoints: /risk/*.
  • wallet:read: Wallet analysis. Endpoints: /scan/wallet, /wallet/*.
  • webhooks:write: Manage webhooks. Endpoints: /webhooks/*.
  • admin: Full access. Endpoints: All endpoints.

​
Example: Read-Only Key

// Key with limited scopes
const key = {
  id: 'key_abc123',
  prefix: 'cg_live_',
  scopes: ['scan:read', 'risk:read'],
  createdAt: '2024-01-15T10:00:00Z'
};

try {
  // This request will succeed
  const scanResponse = await fetch('/v1/scan/url', {
    headers: { Authorization: `Bearer ${apiKey}` }
  });
  if (!scanResponse.ok) {
    const errorBody = await scanResponse.json();
    throw new Error(errorBody?.error?.message ?? 'Scan failed');
  }

  // This request will fail (403 Forbidden)
  const webhookResponse = await fetch('/v1/webhooks', {
    headers: { Authorization: `Bearer ${apiKey}` }
  });
  if (!webhookResponse.ok) {
    const errorBody = await webhookResponse.json();
    throw new Error(errorBody?.error?.message ?? 'Webhook request failed');
  }
} catch (error) {
  console.error('API request failed:', error);
}

​
Rate Limits by Tier

  • Free: $0/mo. 60 req/min. 1,000 daily limit.
  • Pro: $49/mo. 300 req/min. 50,000 daily limit.
  • Enterprise: Custom. 1,000 req/min. Unlimited daily limit.
Rate limits are applied per API key. Multiple keys do not combine limits.

​
Security Best Practices

Never Expose Keys

Never commit API keys to version control or expose in client-side code

Use Environment Variables

Store keys in environment variables or secrets managers

Rotate Regularly

Rotate keys every 90 days as a security practice

Minimum Scopes

Grant only the permissions your application needs

​
Environment Variables

# .env file (never commit this)
CHAINGUARD_API_KEY=cg_live_xxxxxxxxxxxxxxxx

// Usage in code
const apiKey = process.env.CHAINGUARD_API_KEY;

​
Key Management

​
List Keys

GET /v1/auth/keys

{
  "keys": [
    {
      "id": "key_abc123",
      "name": "Production Key",
      "prefix": "cg_live_a1b2",
      "scopes": ["scan:read", "risk:read"],
      "lastUsed": "2024-01-15T14:32:00Z",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

​
Revoke Key

DELETE /v1/auth/keys/{keyId}
Revoked keys immediately stop working. This cannot be undone.

​
Error Codes

  • INVALID_API_KEY (401): Key is malformed or does not exist.
  • EXPIRED_API_KEY (401): Key has been revoked.
  • INSUFFICIENT_SCOPE (403): Key lacks required permissions.
  • RATE_LIMIT_EXCEEDED (429): Too many requests.
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired"
  }
}