Team Collaboration (Full ZK)

These endpoints enable zero-knowledge team sharing. The server processes and stores only public keys, encrypted team memories, and wrapped Data Encryption Keys (DEKs). It never holds cleartext keys or decrypts memory contents.

Session JWT Required

All collaborative team endpoints require the user's primary Supabase Auth session JWT.

1. Create Collaborative Team

Instantiate a new team and registers the owner's self-grant for the data encryption key (DEK).

Request URL

POST /teams

Request Body Schema

{
  "name": "alpha-agents",
  "owner_pubkey": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS1...",
  "owner_wrapped_dek": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."
}

name: Label for the team (1 to 128 characters).
owner_pubkey: The owner's public key (PEM string) used for asymmetric key wrapping.
owner_wrapped_dek: The team's DEK wrapped/encrypted to the owner's public key.

Response (201 Created)

{
  "id": "1a2b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
  "name": "alpha-agents",
  "role": "admin",
  "rotation_seq": 0,
  "created_at": "2026-06-09T16:45:30.123Z"
}

2. Issue wrapped Key Grant

Invite a new member or update their access by publishing the team's DEK wrapped to the recipient's public key.

Request URL

POST /teams/:id/grants

Path Parameters:
- id: The team UUID.

Request Body Schema

{
  "member_id": "0x987654321...",
  "member_pubkey": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS1...",
  "wrapped_dek": "MIIBIjANBgkq...",
  "role": "write"
}

role: The access permission role (admin, write, or read).

Response (201 Created)

{
  "team_id": "1a2b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
  "member_id": "0x987654321...",
  "role": "write"
}

3. Retrieve Member wrapped DEK

Fetch the team's wrapped DEK registered for the caller. The caller can then decrypt it using their private key.

Request URL

GET /teams/:id/grant

Response (200 OK)

{
  "team_id": "1a2b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
  "wrapped_dek": "MIIBIjANBgkq...",
  "member_pubkey": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS1...",
  "rotation_seq": 1
}

4. Revoke Member & Rotate DEK

Revoke a member, increment the team's rotation epoch sequence, and update wrapped DEK records for all remaining members.

Request URL

POST /teams/:id/rotate

Request Body Schema

{
  "revoke_member_id": "0x987654321...",
  "reason": "offboarding",
  "grants": [
    {
      "member_id": "0x123456789...",
      "wrapped_dek": "MIIBIjANBgkq..."
    }
  ]
}

Response (200 OK)

{
  "team_id": "1a2b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
  "rotation_seq": 1,
  "revoked": "0x987654321...",
  "rewrapped": 1,
  "reason": "offboarding"
}

5. Write Encrypted Team Memory

Append a client-encrypted ciphertext block to the team's shared history.

Request URL

POST /teams/:id/memories

Request Body Schema

{
  "ciphertext_b64": "SGVsbG8gV29ybGQ=",
  "agent_key": "sov_live_..."
}

ciphertext_b64: Base64 encoded ciphertext (GCM tag appended). Max decoded size is $256$ KB.

Response (201 Created)

{
  "id": "7a8b9c0d-e1f2-3a4b-5c6d-7e8f9a0b1c2d",
  "seq": 0,
  "rotation_seq": 1,
  "created_at": "2026-06-09T16:45:30.123Z"
}

6. Read Encrypted Team Memories

Retrieve the complete encrypted memory ciphertext history for the team.

Request URL

GET /teams/:id/memories

Response (200 OK)

{
  "team_id": "1a2b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
  "memories": [
    {
      "id": "7a8b9c0d-e1f2-3a4b-5c6d-7e8f9a0b1c2d",
      "seq": 0,
      "rotation_seq": 1,
      "ciphertext_b64": "SGVsbG8gV29ybGQ=",
      "author_id": "0x123456789...",
      "byte_size": 12,
      "created_at": "2026-06-09T16:45:30.123Z"
    }
  ]
}

7. Issue Sub-Key for Team

Create a programmatic API key (sov_live_...) bound to a specific team member grant.

Request URL

POST /teams/:id/subkeys

Request Body Schema

{
  "name": "ci-sync-script",
  "bound_member_id": "0x123456789..."
}

Response (201 Created)

{
  "id": "b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e",
  "name": "ci-sync-script",
  "team_id": "1a2b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
  "bound_member_id": "0x123456789...",
  "masked_key": "sov_live_abc1****************def2",
  "raw_secret": "sov_live_abc1234567890123...def2",
  "created_at": "2026-06-09T16:45:30.123Z"
}

8. Retrieve Team Sync Log

Fetch telemetry statistics detailing multi-agent sync logs.

Request URL

GET /teams/:id/sync-log

Response (200 OK)

{
  "team_id": "1a2b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
  "entries": [
    {
      "agent_key": "0x123456789...",
      "op": "write",
      "bytes": 451,
      "latency_ms": 32,
      "synced_at": "2026-06-09T16:45:30.123Z"
    }
  ]
}

9. Retrieve Membership Roster

List all team members, roles, activation statuses, and grant states.

Request URL

GET /teams/:id/members

Response (200 OK)

{
  "team_id": "1a2b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
  "members": [
    {
      "member_id": "0x123456789...",
      "role": "admin",
      "status": "active",
      "has_grant": true,
      "created_at": "2026-06-09T16:45:30.123Z"
    }
  ]
}

Team Collaboration (Full ZK)

On this page