API reference

Groups

Send sealed messages into a group — including private groups — with a creator-issued bot token. The bot seals ciphertext on its own machine; the API only routes opaque envelopes.

Mint tokens in the sealed app: open a group you created → group info → Bot API tokens. The secret starts with gtk_live_ and is shown once. The bot wallet does not need to be a member. The group id is shown under the group name in that same panel — tap it to copy.

Auth

Pass either a group token scoped to that group, or a member's API key:

Authorization: Bearer gtk_live_… — sender on the relay is the group creator
Authorization: Bearer sk_live_… — only if the key's address is a current member; sender is that address

Discover groups

GET/api/v1/groups

Lists the public group directory — ?mine=1lists the key owner's groups instead (sk_live_… keys only). Each entry carries id, name, verified flag, member count, and whether a join password is set.

Get group + member keys

GET/api/v1/groups/:id

Returns the group view plus memberDeviceKeys— a map of member address → device public keys. When called with a group token (or the creator's own key) the response also includes botTokens: metadata for every minted token — name, prefix, created/revoked timestamps. Secrets are never returned; they are hashed at mint time and shown once. Seal one copy of the plaintext per key (same wire format as the app: SEALEDGRP).

bash

curl https://api.sealedlabs.net/api/v1/groups/$GROUP_ID \
  -H "Authorization: Bearer $SEALED_GROUP_TOKEN"

Post sealed envelopes

POST/api/v1/groups/:id/envelopes

Same envelope fields as POST /api/v1/envelopes. Each toAddress must be a current group member. Plaintext is rejected — seal client-side first.

bash

curl https://api.sealedlabs.net/api/v1/groups/$GROUP_ID/envelopes \
  -H "Authorization: Bearer $SEALED_GROUP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "envelopes": [
      {
        "toAddress": "0x…",
        "recipientDeviceKey": "…",
        "ciphertext": "…",
        "ephemeralPublicKey": "…",
        "nonce": "…"
      }
    ]
  }'

Official (verified) groups cannot mint bot tokens. Revoking a token in the app immediately rejects further Bearer use.

Try it

Try it — fetch a group

GET /api/v1/groups/:id

Use a creator-issued gtk_live_… token, or a member's sk_live_….

TokenGroup id

Try it — send a sealed group message

POST /api/v1/groups/:id/envelopes

Fetches member device keys, seals your message per device in this tab (X25519 + AES-GCM), and posts only ciphertext. With a gtk_live_… token the message arrives from the group creator.

TokenGroup idMessage