Extensions for Zen Social

Zen Social is a community platform. Every community has a home screen made of doors — tiles that open the things the community does: its feed, its calendar, its pictures. An extension adds a door of your own.

When a member taps your door, Zen Social opens your site, signs the member in with OpenID Connect and tells you which community they came from. From there your site can ask Zen Social who the member is, who else is in the community, and send those people a notification.

You host the extension. We host the door, the identity and the API.

Who can build one

Extensions are by invitation while the programme is young. Write to support@zensocial.app with what you want to build and the URL it will live on. We register your app and hand you a client id and a client secret, then grant the communities that asked for it access to install your door.

The handoff

A community admin installs your extension; every member of that community then sees your door on the community's home screen. The door is a plain link, and it opens in a new tab (or the system browser from the installed app):

https://your-site.example/start?installation=42&community=acme

• installation — the id of this community's copy of your extension. It is the id you pass to the API, and it is stable for as long as the extension stays installed.
• community — the community's slug, for a friendly greeting before anyone signs in.

Treat both as hints from an untrusted place: they arrive in a URL a member could edit. The API is the truth. Once the member has signed in, ask Zen Social which installations they can actually see.

Quickstart

1. Get registered. Send us your name, a one-line description, your launch URL (https) and your OAuth redirect URIs. You get a client id and a client secret back.
2. Add OpenID Connect sign-in. We are a standard provider, so point your library at the discovery document below and let it do the rest: authorization code flow, PKCE with S256 (mandatory, for confidential clients too), scopes openid profile. You get an ID token signed with RS256 carrying the member's id, name, avatar and language.
3. Find out where they came from. Read GET /api/extensions/v1/installations with the member's access token. You get every community that has your extension installed and that this member belongs to, with their role in it; match installation.id against the installation parameter the door handed you.
4. Read the community's members with the members scope, if your extension is about people — a rota, a directory, a sign-up sheet.
5. Notify them. Your server gets its own token with the client_credentials grant and posts a notification to a list of members. It lands in Zen Social alongside everything else.

The discovery document, which is the only URL you need to hard-code for sign-in:

https://zensocial.app/.well-known/openid-configuration

And the first call you will make with a member's token:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
     https://zensocial.app/api/extensions/v1/installations

Where to go next

• Building an extension — the whole flow, step by step, with the decisions explained.
• API reference — every endpoint, object, error and limit.

These pages are also available as markdown for language models and other tools: append .md to any of them (for example /docs/extensions/api.md), or start from /docs/extensions/llms.txt.