Authentication

1. Get credentials

Agents register without any prior credentials, using either of these:

• A2A: read /.well-known/agent-card.json , then send SendMessage to https://util.caruana.me/a2a with a data part {"skill":"register","registration":{…}}. See A2A.
• OAuth Dynamic Client Registration (RFC 7591): POST /api/auth/register. Metadata is at /.well-known/oauth-authorization-server .

curl -X POST https://util.caruana.me/api/auth/register \
  -H 'content-type: application/json' \
  -d '{"client_name":"Release checker","contacts":["[email protected]"],"software_id":"example-release-checker","software_version":"2.1.0","grant_types":["client_credentials"],"agent":{"name":"Release checker","description":"Verifies downloaded release artifacts before deployment.","purpose":"Verify SHA-256 checksums of release artifacts and decode their signing certificates.","on_behalf_of":{"name":"Example Corp platform team","type":"organization","contact":"[email protected]"},"runtime":{"model_provider":"Anthropic","model":"claude-sonnet-5-5","framework":"Claude Agent SDK"},"hosting":{"provider":"Cloudflare Workers","country":"US"},"instructions":"Before each deployment, verify every artifact against the published SHA256SUMS and report mismatches.","autonomy":"supervised","intended_operations":["hash_verify","cert_decode"],"expected_volume":"about 50 calls/day","identity":{"agent_card_url":"https://agents.example.com/.well-known/agent-card.json","domain":"example.com"}}}'

People use the credentials form, which includes a Cloudflare Turnstile human check.

The response contains client_id (cu_id_…) and client_secret (cu_sk_…). The secret is shown once: only its SHA-256 hash is stored. Both are 128/256-bit random values from the platform CSPRNG.

2. Call the API

Send the credentials with every request, in one of these two ways:

# HTTP Basic (RFC 7617): simplest
curl -u "$CLIENT_ID:$CLIENT_SECRET" 'https://util.caruana.me/api/hash?algorithm=sha256&input=hello'

# Or exchange them for a 1-hour bearer token (OAuth 2.0 client credentials, RFC 6749 §4.4)
curl -X POST https://util.caruana.me/api/auth/token -u "$CLIENT_ID:$CLIENT_SECRET" -d grant_type=client_credentials
# {"access_token":"cu_at_…","token_type":"Bearer","expires_in":3600}
curl -H "Authorization: Bearer $TOKEN" 'https://util.caruana.me/api/hash?algorithm=sha256&input=hello'

MCP clients: configure the header, e.g. claude mcp add --transport http caruana-utilities https://util.caruana.me/mcp --header "Authorization: Basic <base64 of id:secret>" . Listing tools works without credentials; calling them does not.

3. Expiry and renewal

• New credentials are valid for 30 days.
• POST /api/auth/renew with the same credentials sets expiry to 30 days from now. A longer expiry is never shortened.
• Expired credentials can still be renewed for 90 days after they expire. After that, renewal is refused and you register again.
• Every creation, renewal, refused renewal, token issue and use of expired credentials is recorded in the client's event history.
• GET /api/auth/whoami shows your record, expiry, recent events and a 30-day usage summary: everything that is stored about you.

curl -X POST https://util.caruana.me/api/auth/renew -u "$CLIENT_ID:$CLIENT_SECRET"
# {"client_id":"cu_id_…","renewed":true,"previous_expires_at":"…","expires_at":"…","renewable_until":"…","was_expired":false}

4. Limits

• Per client: 60 requests per minute, counted over the last 60 seconds. Exceeding it returns 429 rate_limited with Retry-After: 60.
• Per IP: a Cloudflare rate-limiting rule protects /api/*, /mcp and /a2a, including registration.

5. Authentication errors

Registration document

Only client_name and agent.purpose are required, but please tell us as much as you can. The response includes a profile_completeness score and lists the fields you left out. Identity claims are recorded as given; this server makes no outbound requests to verify them. Fields we especially value: agent.name, agent.description, agent.on_behalf_of.name, agent.on_behalf_of.type, agent.on_behalf_of.contact, agent.operator.name, agent.runtime.model_provider, agent.runtime.model, agent.runtime.framework, agent.hosting.provider, agent.hosting.country, agent.instructions, agent.autonomy, agent.intended_operations, agent.identity.agent_card_url, contacts.