Platform API multitenancy

The Platform API lets you build multi-tenant products on 1Claw. You register an app, define a bootstrap template, provision users, and hand each user a claim URL, all without your platform being able to read their secrets.

• Templates create a vault, agents, and policies in one atomic operation
• In templates use nested intents: { enabled: true }, not the flat intents_api_enabled
• signing_keys in the template are provisioned server-side; the plt_ key cannot read them across the org boundary
• Bootstrap returns claim_url plus a one-time agent_api_key in summary

1. 1

   Exchange your API key for a user JWT. Replace 1ck_your_key_here with your real key.

   bash Copy

   export ONECLAW_API_KEY="1ck_your_key_here"
   export USER_JWT=$(curl -s -X POST https://api.1claw.co/v1/auth/api-key-token \
     -H "Content-Type: application/json" \
     -d "{\"api_key\":\"$ONECLAW_API_KEY\"}" | jq -r .access_token)

2. 2

   Register a platform app with your user JWT. Silent auth skips the interactive consent screen; use 'interactive' if your platform requires explicit user approval.

   bash Copy

   curl -X POST "https://api.1claw.co/v1/platform/apps" \
     -H "Authorization: Bearer $USER_JWT" -H "Content-Type: application/json" \
     -d '{ "name": "My DeFi Platform", "slug": "my-defi", "auth_mode": "silent" }'

3. 3

   Save the plt_ key now: it is shown only once. Use $PLT_KEY as Bearer in later steps.

   bash Copy

   # Save from the response:
   export APP_ID="paste-app-id-from-response"
   export PLT_KEY="paste-plt-key-from-response"

4. 4

   Create a bootstrap template. Note intents is a nested object here.

   bash Copy

   curl -X POST "https://api.1claw.co/v1/platform/apps/$APP_ID/templates" \
     -H "Authorization: Bearer $PLT_KEY" -H "Content-Type: application/json" \
     -d '{
       "name": "default-template",
       "spec": {
         "vault": { "name": "user-vault" },
         "agents": [{ "name": "defi-bot", "intents": { "enabled": true } }],
         "signing_keys": [{ "chain": "ethereum" }],
         "policies": [{ "principal_ref": "agents.primary", "vault_ref": "vault", "paths": ["keys/*"] }]
       }
     }'

5. 5

   Save the template ID from the response.

   bash Copy

   export TEMPLATE_ID="paste-template-id-from-response"

6. 6

   Upsert a user.

   bash Copy

   curl -X POST "https://api.1claw.co/v1/platform/users/upsert" \
     -H "Authorization: Bearer $PLT_KEY" -H "Content-Type: application/json" \
     -d '{ "email": "user@example.com", "external_subject": "telegram:123456789" }'

7. 7

   Save the connection_id from the upsert response.

   bash Copy

   export CONNECTION_ID="paste-connection-id-from-response"

8. 8

   Bootstrap the user from the template. The response has claim_url and a one-time summary.agent_api_key.

   bash Copy

   BOOTSTRAP_RESPONSE=$(curl -s -X POST "https://api.1claw.co/v1/platform/connections/$CONNECTION_ID/bootstrap" \
     -H "Authorization: Bearer $PLT_KEY" -H "Content-Type: application/json" \
     -d '{ "template_id": "'$TEMPLATE_ID'" }')

9. 9

   Share the claim_url with the user. It expires in 10 minutes; reissue with the reissue-claim endpoint if it lapses.

   bash Copy

   echo "Claim URL: $(echo $BOOTSTRAP_RESPONSE | jq -r .claim_url)"
   # Format: https://1claw.co/connect/{slug}/claim/{token}

You now register a platform app and bootstrap a user with a vault, an intents-enabled agent, and server-side signing keys your platform cannot read, plus a claim URL to hand off.

Where this goes wrong in practice. Multi-tenancy failures are rarely subtle and almost always consequential, because the blast radius is every customer at once.

• platform_locked is omitted at provisioning. It is far easier to set at creation than to retrofit once support workflows have grown to depend on operator reads.
• The plt_ key reaches client code. It is a platform-wide credential; anywhere it appears in a browser bundle it is published to every visitor.
• Bootstrap runs without an idempotency key. Retries then double-provision, and the second set of resources is attributed to the same connection.
• Delegation scopes are set broadly during development. secrets:read added for debugging tends to stay, and it applies across every connected user rather than one.
• Claim tokens are treated as durable links. They are one-time and expiring, so a token pasted into a ticket for later is a support case waiting to happen.