Agents as first-class principals

In 1Claw an agent is a real principal with its own identity, not a shared human login. An agent can authenticate three ways: an API key with the ocv_ prefix, mutual TLS, or OIDC federation. This lesson uses the API key path because it's the fastest to run end to end.

• API key: ocv_ random value, argon2-hashed, shown once at creation
• mTLS: client certificate identity for infrastructure agents
• OIDC: federate an external identity provider into 1Claw

1. 1

   Use the same 1ck_ key from Foundations. Agent keys cannot create other agents.

   bash Copy

   export ONECLAW_API_KEY="1ck_your_key_here"

2. 2

   Register an agent. The plaintext ocv_ key is returned once in this response and never again. Use the vault UUID from Foundations (1claw vault list) and export it: export VAULT_ID=...

   bash Copy

   export VAULT_ID="your-vault-uuid-here"
   
   AGENT_RESPONSE=$(curl -s -X POST https://api.1claw.co/v1/agents \
     -H "Authorization: Bearer $ONECLAW_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name":"web-backend","token_ttl_seconds":900,"vault_ids":["'$VAULT_ID'"]}')
   
   echo "$AGENT_RESPONSE"

3. 3

   Extract the agent id and api_key from the response. The response looks like: {"agent":{"id":"7e3ce911-...","name":"web-backend",...},"api_key":"ocv_..."}. Save both values as env vars.

   bash Copy

   export ONECLAW_AGENT_ID=$(echo "$AGENT_RESPONSE" | jq -r .agent.id)
   export ONECLAW_AGENT_KEY=$(echo "$AGENT_RESPONSE" | jq -r .api_key)
   echo "Agent ID: $ONECLAW_AGENT_ID"
   echo "Agent Key: $ONECLAW_AGENT_KEY"

4. 4

   Exchange the agent credentials for a short-lived JWT. This endpoint needs no bearer token; the credentials in the body are the auth.

   bash Copy

   TOKEN=$(curl -s -X POST https://api.1claw.co/v1/auth/agent-token \
     -H "Content-Type: application/json" \
     -d '{"agent_id":"'$ONECLAW_AGENT_ID'","api_key":"'$ONECLAW_AGENT_KEY'"}' | jq -r .access_token)

5. 5

   Confirm the token works by fetching the agent's own profile. You should see the ssh_public_key and ecdh_public_key fields.

   bash Copy

   curl -s https://api.1claw.co/v1/agents/me -H "Authorization: Bearer $TOKEN"

You now have a registered agent and a fresh JWT bound to its vaults and TTL. Later calls use a Bearer JWT like this one; you will refresh it when policies change.