Skip to main content

Connect your Matrix server and verify Sparks

Updated: August 2026

This guide shows how to connect your own Matrix homeserver to Sparks and verify the Sparks session as a client (device verification with Element).

Sprache / Language: Deutsch

Short film (about 1 minute, German voiceover)​

Which path do I need?​

GoalWhereWho
Org homeserver (Legacy Synapse) for the whole teamAccount → Team → ServicesTeam admins
Additional Matrix account (e.g. matrix.org or another server)Sparks → Settings → AccountsAny user
Verify the Sparks device with ElementSparks → Settings → SecurityUsers with an existing Element device

The recommended default for Sparks organizations is Matrix via OIDC/SSO (Keycloak). “Own server (Legacy Synapse)” and external Matrix accounts are special cases for existing homeservers or extra identities.

Background on encryption and recovery keys: End-to-end encryption. Admin overview: Team management.

Part A — Org homeserver (Legacy Synapse)​

Use this when every team member should use the same existing Synapse with username/password (not the standard OIDC flow).

Prerequisites​

  • You are a team admin in the Account area (account-preview.sparks.team during beta).
  • The homeserver URL is reachable over HTTPS, e.g. https://matrix.example.com.
  • Members know their Matrix credentials on that server.
  • The homeserver allows login from the Sparks client (CORS / Client API).

Steps (admin)​

  1. Open the Account area → Team.
  2. Scroll to Services for your team → Matrix access.
  3. Choose Own server (Legacy Synapse).
  4. Enter the server address (e.g. https://matrix.example.com) and save.

📸 Screenshot: Matrix access in Account Team

Steps (members after the switch)​

  1. Sign in to Sparks as usual (SSO/Keycloak).
  2. The dialog Connect Matrix (Synapse) appears with the configured homeserver URL.
  3. Enter Matrix username and Matrix password → Connect.
  4. Sparks then syncs rooms and messages from that homeserver.

Part B — Add another Matrix account (any homeserver)​

Use this when you want an account on another homeserver in addition to the organization account (e.g. matrix.org or a private server).

Steps​

  1. In Sparks open Settings (Ctrl+. / Cmd+.) → Accounts tab.
  2. On the Matrix card, click Manage.
  3. Choose Add Matrix account.
  4. Enter server name or homeserver URL (preset: matrix.org) → Continue.
    Sparks discovers the homeserver via .well-known.
  5. Sign in with password and/or SSO.

📸 Screenshot: Settings Accounts with Matrix

📸 Screenshot: Add Matrix account dialog

The new account is marked External. You can switch between org and external accounts. Recovery keys for external accounts stay on-device and are not uploaded to Sparks.

Part C — Verify Sparks as a client with Element​

So encrypted chats stay readable and trusted across devices, verify the new Sparks session against an already verified device (typically Element).

Prerequisites​

  • Matrix E2EE is enabled for your organization (Security policies).
  • You are signed into Sparks with the same Matrix account as in Element (@user:server).
  • Element (web, desktop, or mobile) is open and online.

Option 1 — Start from Sparks (recommended)​

  1. Open Settings → Security.
  2. In Device verification & key restore, click Verify this device with Element.
  3. In Element, accept the incoming verification request.
  4. On both sides, compare the shown numbers and emoji.
  5. Only if they match: click Accept in Sparks and confirm in Element.

📸 Screenshot: Settings Security – device verification

📸 Screenshot: Device verification – compare codes

Option 2 — First-run onboarding​

On first login, the Secure your chat wizard may appear:

  1. Choose Send verification request to my devices (or skip for later).
  2. Accept in Element and compare codes as above.
  3. Complete encryption / recovery-key steps in the wizard if prompted.

Option 3 — Start from Element​

  1. In Element under Settings → Sessions (or Security), select the new Sparks session for verification.
  2. Sparks shows the Device verification dialog.
  3. Compare codes → Accept.

Tips​

  • Only confirm if the codes match on both devices. If they differ, cancel and restart.
  • After successful verification, Sparks can restore keys from backup so older encrypted messages become readable.
  • With the Strict policy, the organization does not store the recovery key on the server; keep the key offline. Details: E2EE.

Quick checklist​

  • Homeserver URL known and reachable
  • Org mode chosen (OIDC or Legacy Synapse) or external account added
  • Signed in to Sparks and Element with the same Matrix ID
  • Device verification (emoji/numbers) completed
  • Optional: recovery key saved (especially under Strict policy)

See also​