Linked platforms

Sign in to Synaplan from Nextcloud, ownCloud or OpenCloud with the account you already have. A linked platform is a partner server that has registered itself with your Synaplan instance. Its users connect once, in the browser, while signed in to Synaplan — and from then on the partner app works under their own Synaplan identity, with a scoped API key they can revoke at any time.

The Outlook add-in (Synamail) uses the same connect page and is always on.

Status: shipped in the September 2026 roadmap (wave 2, "More Nextcloud" sprint 1) on the Synaplan side. It is off by default (PLATFORM_LINKS.ENABLED). The Nextcloud app gains a link existing account mode in the next sprint; until then Nextcloud keeps provisioning per-user accounts as described on the Plugins & Integrations page.

In three sentences

A partner instance (one Nextcloud server, say) registers with Synaplan once and gets an instance id and secret. When one of its users clicks Connect to Synaplan, the partner sends them to Synaplan's connect page, where they sign in with their normal Synaplan account and get a link code; the partner exchanges that code for an API key that belongs to that very user. Ownership, chats and files never move — the partner just acts as the user.

Who this is for

You are… What changes
A person who uses Synaplan in the browser and Nextcloud at work One click links the two. Your Nextcloud AI features run on your Synaplan account — your files, your memories, your usage.
A Nextcloud / ownCloud / OpenCloud administrator You register your server once and no longer hand out a shared key or maintain a second set of accounts.
A Synaplan operator You decide which partner servers may link (approve / revoke), and every step is audited.

For users: connect and disconnect

  1. In the partner app (for example Nextcloud → Synaplan Integration) choose Connect to Synaplan.
  2. Your browser opens Synaplan's connect page. If you are not signed in, sign in as usual — the page returns you to the connect step afterwards.
  3. Confirm. Synaplan issues a one-time code and sends you back to the partner, which exchanges it for a key in the background. You never see or paste a key.

Under Channels & integrations → Linked platforms you see every link you hold — platform, host, your external id there, and the key name. Disconnect revokes that key on the spot; the partner app has to link again. The same key also shows up on your API-keys page with a linked platform badge.

Link codes expire after five minutes and are single-use. You can issue at most 20 per hour.

For operators: turn it on and approve partners

Everything under /api/v1/platform-links/* and /api/v1/me/platform-links* is gated by PLATFORM_LINKS.ENABLED (BCONFIG group PLATFORM_LINKS, owner 0, seeded 0). With the flag off those routes answer 404 and the UI is unchanged.

INSERT INTO BCONFIG (BOWNERID, BGROUP, BSETTING, BVALUE)
VALUES (0, 'PLATFORM_LINKS', 'ENABLED', '1')
ON DUPLICATE KEY UPDATE BVALUE = '1';

Rollback is the same statement with '0'. Registered instances and existing links stay in the database; keys already issued keep working until revoked.

Pending and active instances

Registered by Initial status Can issue link codes?
A signed-in Synaplan administrator active yes
A regular user, or anonymously pending no — until you approve it

Operate → People → Linked platforms lists every registered server with client, host, status and last seen. Approve activates a pending server; Revoke blocks it and revokes every key it ever issued. Anonymous registration is limited to 10 per hour per address.

What is audited

Every register, approve, revoke, link and disconnect writes a row to People → Audit (platform_instance.*, platform_link.*). A redirect target that does not match what the instance registered is refused and logged as platform_link.redirect_rejected. Rows never include content or keys.

For partner developers: the handshake

Four calls, all JSON. Full request and response schemas are in the Swagger UI under the tag Platform Links.

Step Who Call
1. Register once partner server POST /api/v1/platform-links/instances with client (nextcloud / owncloud / opencloud), host, redirect_uris[] → instance_id, instance_secret, status
2. Check status partner server GET /api/v1/platform-links/instances/self with headers X-Instance-Id / X-Instance-Secret → status, host, client
3. Issue a code the user's browser, signed in to Synaplan POST /api/v1/platform-links/codes with instance_id, external_id (the user's id on your side, ≤ 191 chars), redirect_uri, state (≤ 512 chars), optional with_memories → redirect (your redirect URI with code and state appended)
4. Exchange partner server POST /api/v1/platform-links/exchange with instance_id, instance_secret, code → api_key (id, key, name, scopes), user (id, email, display_name), link_id

Rules the server enforces:

  • Redirect URIs are prefix-matched against what you registered: same host, same port, HTTPS everywhere except localhost / 127.0.0.1 in development. Wildcard hosts cannot be registered. A registered root URI (https://cloud.example.org) matches every path on that origin.
  • The key scopes are chat, files, rag, plus memories when the user's link was issued with with_memories: true. Nothing else — the key cannot manage users, groups or the instance.
  • A code is single-use: a second exchange fails even when two requests race.
  • Linking an external_id that was already linked to a different Synaplan account revokes that earlier key and moves the link to the new account, so one Nextcloud user is never two Synaplan users at once. The move is audited under both accounts; the previous account no longer sees the link and can no longer disconnect it.
  • The Outlook add-in does not register: it uses the built-in instance and POST /api/v1/addin/connect, which mints the add-in key and builds the relay redirect on the server. See the Synamail repository's docs/AUTH_FLOW.md.

A runnable reference of the whole flow — flag off, register, approve, code, exchange, replay, disconnect — is _devextras/testing/platform-links/fake-instance.sh in the synaplan repository.

What does not change

  • Provisioned per-user accounts, shared-key mode and existing partner API keys keep working exactly as before. Linking is an additional mode, not a migration.
  • Public links, widgets, mobile apps, the /v1 gateways and OIDC login keep their contract.
  • Administrators approve servers; they never see a user's key or content.

Related pages