Security Model

​

Per-Grant Binding and Isolation

• Natural isolation: Each consent grant’s user data is only visible to the Agent it is bound to; cross-Agent access is permanently blocked
• No privilege creep: No special roles like Admin or Super User; permissions are explicit, fixed, and scoped by capability
• Audit-friendly: Each grant relationship is clear and easy to trace, facilitating log auditing and compliance checks

​

Two-Layer Authentication

1. API Key — Identifies the Agent (connection layer), managed by the Agent application provider
2. User consent grant — Identifies one authorized delivery user; one consent grant maps to one user and is valid for 90 days by default, obtained through the binding flow (SMS code / H5)

Each user must authorize in person, once. The platform offers no Admin silent binding — there is no back-office credential that can skip authorization on a user’s behalf (the legacy ADMIN_SECRET / trusted binding has been removed). A user authorization can only be started via request_user_bind (SMS by default / H5) and completed by the user themselves via verify_user_bind.

​

API Key (Agent Identification)

• Prefix: Starts with clw_, followed by random characters, e.g. clw_a1b2c3d4...
• Storage: Server only stores a hash, never plaintext; each request is compared by hash
• Issuance: Generated when creating an Agent in the Portal, displayed only once — if lost, regenerate it
• Usage: Passed in the connection-layer HTTP Header as Authorization: Bearer {API_KEY} to identify the calling Agent

​

Consent Grant (User Identification)

• Prefix: Starts with cg_
• One-to-one: One consent grant maps to one user (binds an “Agent + user + capability” triple)
• Validity: 90 days by default; once it expires or rotates, the user must re-bind
• Source: Obtained after the user authorizes in person through the binding flow (SMS code / H5); verify_user_bind returns consent_grant_id, scopes, and expires_at (ISO 8601) on success
• Storage: The plaintext is returned only once; only a hash is stored — keep it safe
• Transport: passed as the consent_grant_id argument on each MCP tool (never in the body, never in a header)
• Invalidation: Once expires_at is reached, or after being revoked via revoke_user_bind, it becomes invalid immediately; re-bind to obtain a new one

​

Data Encryption

​

Agent-User Isolation

Access Rules:
┌─────────────────────────────────────────────┐
│ Agent A's API Key + consent grant 1         │
│ → Can only access User 1's data             │
│ → Cannot access User 2's data               │
│ → Cannot access Agent B's data              │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ Agent B's API Key + consent grant 2         │
│ → Can only access User 2's data             │
│ → Cannot access User 1's data               │
│ → Cannot access Agent A's data              │
└─────────────────────────────────────────────┘

1. Every authorized request carries an API Key and a consent_grant_id
2. The server verifies the API Key and resolves the agent_id
3. The server verifies the consent_grant_id, locating the authorized user and its granted capability
4. Database query condition: WHERE agent_id = ? AND user_id = ?
5. Any query crossing these two conditions is rejected (a grant for another capability / provider returns CONSENT_GRANT_WRONG_CAP; a capability not enabled returns CAP_NOT_BOUND)

​

Consent Grant Lifecycle

​

Authentication Failure Handling

​

Security Best Practices

​

FAQ