Registering Agents

This guide covers the full agent registration process, including all configuration options, key management, and lifecycle operations.

Registration

Request

curl -X POST https://api.clawgrc.com/api/v1/agents \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "security-scanner",
    "agent_type": "security",
    "description": "Automated vulnerability scanner for web applications",
    "capabilities": [
      "grc.trigger_scan",
      "grc.create_finding",
      "grc.create_ticket",
      "grc.list_findings"
    ],
    "data_classifications": ["internal", "confidential"],
    "certificate_fingerprint": "sha256:AB:CD:EF:12:34:56:78:90...",
    "metadata": {
      "version": "2.1.0",
      "runtime": "python-3.13",
      "owner_team": "security-engineering"
    }
  }'

Request Fields

Field	Type	Required	Description
name	string	Yes	Human-readable name for the agent
agent_type	string	Yes	Agent function: compliance, security, monitoring, remediation, audit
description	string	No	Description of the agent's purpose
capabilities	string[]	No	MCP tools this agent is authorized to use (default: [])
data_classifications	string[]	No	Data sensitivity levels: public, internal, confidential, restricted
certificate_fingerprint	string	No	SHA-256 fingerprint of the agent's TLS client certificate
metadata	object	No	Arbitrary key-value metadata for organizational use

Response

{
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "api_key": "cgrc_ABCDEFghijklmnopqrstuvwxyz1234567890ABCD"
}

warning

The api_key is returned only once. Store it securely (e.g., in a secrets manager). It cannot be retrieved after this response.

Agent Types

Type	Description	Typical Capabilities
compliance	Manages compliance data, evidence, and frameworks	grc.list_frameworks, grc.get_compliance_score
security	Performs security assessments and scanning	grc.trigger_scan, grc.create_finding, grc.create_ticket
monitoring	Monitors systems and reports status	grc.get_compliance_score, grc.list_findings
remediation	Fixes issues identified by other agents	grc.list_findings, grc.create_ticket
audit	Reviews compliance data and generates reports	grc.list_frameworks, grc.list_findings, grc.get_compliance_score

Capabilities and RBAC

The capabilities array defines which MCP tools an agent can invoke. When an agent sends a tool invocation through MCP, the platform checks that the tool name is listed in the agent's capabilities. If not, the invocation is denied with a permission_denied error.

You can grant broad access with the wildcard capability "*", but this is not recommended for production agents.

Available Capabilities

Capability	Description
grc.list_frameworks	List compliance frameworks
grc.get_compliance_score	Get compliance score and breakdown
grc.create_finding	Create security findings
grc.create_ticket	Create remediation tickets
grc.list_findings	List and filter findings
grc.trigger_scan	Trigger security scans
grc.call_agent	Invoke another registered agent
grc.discover_agents	Find agents by capability and trust score

API Key Management

Authentication

Agents authenticate by sending their API key in the X-API-Key header:

curl -H "X-API-Key: cgrc_YOUR_AGENT_KEY" https://api.clawgrc.com/api/v1/...

API keys are stored as SHA-256 hashes in the database. The plaintext key is never stored.

Key Rotation

Rotate an agent's API key without downtime:

curl -X POST https://api.clawgrc.com/api/v1/agents/{agent_id}/rotate-key \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "api_key": "cgrc_NEWKEYxyz..."
}

The old key is immediately invalidated. Update your agent's configuration with the new key.

tip

Rotate API keys regularly (every 90 days at minimum) as part of your credential management policy.

Updating Agents

Update mutable agent properties without re-registering:

curl -X PUT https://api.clawgrc.com/api/v1/agents/{agent_id} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": [
      "grc.list_frameworks",
      "grc.get_compliance_score",
      "grc.create_finding",
      "grc.create_ticket",
      "grc.trigger_scan"
    ],
    "metadata": {
      "version": "2.2.0"
    }
  }'

Updatable fields: name, description, capabilities, data_classifications, status, certificate_fingerprint, metadata.

Deregistering Agents

Deregister an agent by setting its status to inactive:

curl -X DELETE https://api.clawgrc.com/api/v1/agents/{agent_id} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

This is a soft delete -- the agent record is retained for audit trail integrity, but the agent can no longer authenticate or open MCP sessions.

Listing Agents

# List all active agents
curl https://api.clawgrc.com/api/v1/agents?status=active \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Response
{
  "agents": [
    {
      "id": "uuid",
      "name": "compliance-bot",
      "agent_type": "compliance",
      "trust_score": 0.85,
      "status": "active",
      "capabilities": ["grc.list_frameworks", "grc.get_compliance_score"],
      "created_at": "2025-01-01T00:00:00Z"
    }
  ],
  "total": 3,
  "limit": 50,
  "offset": 0
}

Agent Discovery

Other agents can discover your agent through the discovery endpoint:

curl -X POST https://api.clawgrc.com/api/v1/agents/discover \
  -H "X-API-Key: cgrc_..." \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": ["grc.trigger_scan"],
    "min_trust_score": 0.7,
    "status": "active"
  }'

This returns agents that have the requested capabilities and meet the minimum trust score threshold, sorted by trust score descending.

Best Practices

• Apply least privilege -- Only grant the capabilities an agent actually needs. Never use "*" in production.
• Use descriptive names -- Name agents clearly so team members understand their purpose at a glance.
• Add metadata -- Include version, runtime, and owner team information to make agent management easier.
• Rotate keys regularly -- Treat API keys like passwords. Rotate every 90 days.
• Monitor trust scores -- Set up alerts for trust score drops below 0.5. Investigate the cause before the agent becomes flagged.
• Use certificate pinning -- For high-security agents, configure a certificate fingerprint and enforce mutual TLS.