# 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](mailto: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:

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

## Where to go next

- [Building an extension](/docs/extensions/guide) — the whole flow, step by step, with the decisions
  explained.
- [API reference](/docs/extensions/api) — 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`](/docs/extensions/llms.txt).