Authentication

ClawNex uses different authentication methods depending on the endpoint type and whether RBAC is enabled.

API Key Authentication (Public API)

Public API endpoints (/api/v1/*) use API key authentication regardless of the RBAC setting.

Key Format

cnx_<40 hex characters>

Example: cnx_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Keys are never stored in plaintext. On creation, the key is hashed with SHA-256 and only the hash is persisted. The plaintext key is returned exactly once at creation time.

Providing the Key

Primary format (recommended):

X-ClawNex-Key: cnx_YOUR_KEY_HERE

OpenAI-compatible format (required for chat completions):

Authorization: Bearer cnx_YOUR_KEY_HERE

Both formats are accepted on all endpoints. If both are present, X-ClawNex-Key takes precedence.

Available Scopes

Scope	Grants Access To
`shield:scan`	`POST /api/v1/shield/scan`
`shield:read`	Reserved for future shield statistics endpoints
`agents:read`	`GET /api/v1/agents`
`alerts:read`	`GET /api/v1/alerts`
`audit:read`	`GET /api/v1/audit`
`fleet:read`	`GET /api/v1/fleet`
`chat:completions`	`POST /api/v1/chat/completions`

Assign only the scopes required for the integration (principle of least privilege).

Creating Keys

Via Dashboard:

Navigate to Configuration > API Keys
Click Create API Key
Enter a name, select scopes, optionally set a custom rate limit (default: 60 req/min)
Click Generate and copy the key immediately

Via API:

curl -X POST http://127.0.0.1:5001/api/config/api-keys \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD Pipeline", "scopes": ["shield:scan", "alerts:read"]}'

⚠️

The plaintext key is shown exactly once at creation. Store it in a secrets manager immediately. If lost, revoke the key and generate a new one.

Session Authentication (Dashboard / Internal API)

When RBAC is enabled (RBAC_ENABLED=true), internal API endpoints (/api/*) require a valid session cookie (clawnex_session).

CSRF Protection

Mutation endpoints (POST, PUT, PATCH, DELETE) on internal routes require a CSRF token via the X-CSRF-Token header when RBAC is enabled.

Authentication Summary

Endpoint Pattern	Auth Method	RBAC Impact
`/api/v1/*` (public)	API key (`X-ClawNex-Key`)	None — works the same with or without RBAC
`/api/*` (internal, read)	Session cookie (`clawnex_session`)	Required when RBAC is enabled
`/api/*` (internal, write)	Session cookie + CSRF token	Required when RBAC is enabled
MCP Server	MCP protocol (localhost CORS)	Not affected

Key Rotation

Create the new key before revoking the old one
Update all integrations to use the new key
Verify traffic is flowing with the new key (check last_used_at)
Revoke the old key
Rotate keys every 90 days or after any suspected compromise

Overview Public API (v1)