How Authentication Works

ClawAuth uses cryptographic challenge-response authentication with ECDSA P-256 signatures. This provides strong security without shared secrets or passwords.

Overview

Unlike traditional username/password systems, ClawAuth authentication is based on public key cryptography. Each agent has a unique ECDSA P-256 keypair:

• Private Key: Kept secret by the agent, used for signing
• Public Key: Registered with ClawAuth, used for verification

Authentication Flow

The authentication process follows these steps:

POST /auth/challenge
{
  "agentId": "agent_abc123"
}

Response:
{
  "challengeId": "chal_xyz789",
  "nonce": "random-256-bit-string",
  "expiresAt": "2026-02-09T14:30:00Z"
}

// Agent side (automatic in SDK)
const signature = privateKey.sign(nonce, 'SHA256');
const hexSignature = signature.toString('hex');

POST /auth/authenticate
{
  "challengeId": "chal_xyz789",
  "signature": "30440220123abc..."
}

Response:
{
  "accessToken": "eyJhbGciOiJFUzI1Ni...",
  "refreshToken": "rf_abc123...",
  "expiresIn": 3600
}

// ClawAuth server side
const publicKey = await getAgentPublicKey(agentId);
const isValid = publicKey.verify(nonce, signature, 'SHA256');

if (isValid) {
  return generateJWT(agentId, permissions);
} else {
  throw new Error('Invalid signature');
}

JWT Tokens

Upon successful authentication, ClawAuth issues standard JWT tokens signed with ES256 (ECDSA using P-256 and SHA-256):

Access Token

Short-lived token (1 hour) containing agent identity and permissions:

{
  "sub": "agent_abc123",           // Agent ID
  "aud": "service_xyz789",         // Service ID  
  "roles": ["user", "api_access"], // Assigned roles
  "permissions": ["read", "write"], // Computed permissions
  "trustScore": 8.7,               // Current trust score
  "iat": 1707566400,               // Issued at
  "exp": 1707570000,               // Expires at
  "jti": "jwt_unique_id"           // Token ID
}

Refresh Token

Longer-lived token (30 days) for obtaining new access tokens without re-authentication:

POST /auth/refresh
{
  "refreshToken": "rf_abc123..."
}

Response:
{
  "accessToken": "eyJhbGciOiJFUzI1Ni...",
  "refreshToken": "rf_def456...",  // New refresh token
  "expiresIn": 3600
}

Security Properties

Secure Enclave Support

For maximum security, ClawAuth supports hardware-backed keys using Apple's Secure Enclave, TPM modules, or HSMs. Private keys stored in these secure elements cannot be extracted, even with root access.

// Generate key in Secure Enclave (iOS/macOS)
const keychain = new SecureEnclave();
const keypair = await keychain.generateKey({
  algorithm: 'ECDSA',
  curve: 'P-256',
  keyUsage: ['sign'],
  extractable: false  // Key cannot leave Secure Enclave
});

// Register public key with ClawAuth
await ClawAuthAgent.register({
  email: '[email protected]',
  name: 'Hardware-backed Agent',
  publicKey: keypair.publicKeyPEM
});

Implementation Notes