Humans vs Agents

There are two kinds of principal. Humans create vaults, store secrets, and write policies. Agents are AI assistants or automations that fetch secrets at runtime. Same base URL, same endpoints; only the way you authenticate and what you're allowed to see differ.

• Human key prefix: 1ck_ (personal API key). It works directly as a Bearer token, or you can exchange it at POST /v1/auth/api-key-token.
• Agent key prefix: ocv_ (agent API key). Exchange it at POST /v1/auth/agent-token, sending BOTH agent_id and api_key.
• Do not mix them. A 1ck_ key on the agent-token endpoint, a missing agent_id, or an empty variable all return 401 Invalid credentials.
• Agent JWTs are short-lived (about 1 hour). Refresh by exchanging the key again.
• An agent with a key but no policy sees zero secrets.

1. 1

   Human path. Your 1ck_ key is already a Bearer token, so you can call the API with no exchange step.

   bash Copy

   export ONECLAW_API_KEY="1ck_your_user_key"
   curl -s https://api.1claw.co/v1/vaults -H "Authorization: Bearer $ONECLAW_API_KEY"

2. 2

   Prefer a short-lived JWT for the human key? Exchange it at the api-key-token endpoint. This is a different endpoint from the agent one.

   bash Copy

   curl -s -X POST https://api.1claw.co/v1/auth/api-key-token \
     -H "Content-Type: application/json" \
     -d "{\"api_key\":\"$ONECLAW_API_KEY\"}"

3. 3

   Agent path. First, create an agent using your human 1ck_ key. Use the VAULT_ID from Lesson 2, or copy a vault id from the Step 1 response. Export it if not already set. The response contains the agent_id and a plaintext api_key (starts with ocv_). Save both: the ocv_ key is shown only once.

   bash Copy

   # Make sure VAULT_ID is set (from Lesson 2 or Step 1 above)
   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\":\"my-first-agent\",\"token_ttl_seconds\":3600,\"vault_ids\":[\"$VAULT_ID\"]}")
   echo "$AGENT_RESPONSE"

4. 4

   Extract agent_id and api_key from the response above. The ocv_ key is shown only at creation time: save it somewhere safe.

   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  KEY=$ONECLAW_AGENT_KEY"

5. 5

   Exchange the agent credentials for a short-lived JWT. Send agent_id AND api_key. Both are required. Capture the token for the next step.

   bash Copy

   export AGENT_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)
   echo "AGENT_TOKEN=$AGENT_TOKEN"

6. 6

   Verify the token works by calling the agents/me endpoint. You should see the agent's metadata.

   bash Copy

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

7. 7

   Both paths give you a Bearer credential. Use it on the same secret endpoints. The agent only sees what a policy has granted.

   json Copy

   {
     "access_token": "eyJhbGciOiJFZERTQSIs...",
     "token_type": "Bearer",
     "expires_in": 3600
   }

You've authenticated both ways: a human 1ck_ key used as a Bearer token, and an agent ocv_ key exchanged (with its agent_id) for a JWT. Same API, different door.