# API keys and webhooks

> Connect EmmauOS to Zapier, Make, n8n or your own code with a church key. Each key has a name, the scopes you tick, and an end date. Webhooks send new results, people and stage moves as they happen.

For: Admin, Owner
Canonical: https://emmauos.com/docs/api-and-webhooks

## Keys

On Settings → Connections → AI agents, under **API keys**, press **New key**. Give it a name (*Zapier for the connect team*), tick only the scopes it needs, and choose how long it lives (a year by default). The key shows once; copy it into the tool that will use it. EmmauOS keeps only a fingerprint.

Keys come with Growing and Large. Only an owner or admin makes or revokes one, and every change is in the history with their name. **Revoke** stops a key at once and removes the webhooks it added.

| Scope | What it allows |
|---|---|
| people:read | People who said the team may contact them: name, email, source and when they were added. |
| people:write | Add a person, or a plain line on their timeline. Nobody is contacted. |
| results:read | Results as gift bands. Never answers, stories or notes. |
| stages:read | Your tracks and where people are on them. |
| stages:suggest | Suggest a stage move. Staff confirm it on the person's page. |
| sources:read | Your sources and their links. |
| webhooks:manage | Add and remove its own webhooks, as Zapier does. |

## What a key never sees

A key gets less than an AI agent. It never sees the words of *something I have walked through*, how someone came to faith, confirmations, conversations, giving, gifts of the Spirit, anyone who may be under 18, or anyone who didn't say the team may contact them. Results come as bands, never a ranking or a maturity score. A key can't send a message, change a stage on its own, or read another church.

## Webhooks

Under **Webhooks**, press **Add webhook**, paste an `https://` address, and tick the events:

| Event | When it is sent |
|---|---|
| result.completed | Someone finishes the assessment. |
| person.added | Someone is added to People. |
| person.stage_changed | Someone moves to a new stage. |
| person.erased | Someone is erased. Only their id is sent, so copies elsewhere can be deleted. |

The signing secret shows once. Each send waits about 20 seconds, then checks the person again, so a result someone keeps private is never sent. A send that fails is tried again for a day, then the webhook pauses and the list says why. **Deliveries** shows the last 30 days, and **Send again** retries one.

Webhooks come with every paid plan. A webhook an AI agent prepares waits until an admin copies its secret here.

## Sending is yours

EmmauOS never contacts anyone on its own, and a key doesn't change that. When your Zap emails a new person, your church sends that email from your own tool. What you send through your own keys goes where you send it, under your own privacy notice.

## For developers

Send the key as `Authorization: Bearer eos_key_…` to `/api/v1/integration`. Each key may make 60 requests a minute. Check each webhook with the `EmmauOS-Signature` header: `t=` is the time and `v1=` is an HMAC-SHA256 of `t.body` with your secret. The [API reference](/docs/api-reference) lists every route, field and event, with an example. To connect through Zapier, see [Zapier](/docs/zapier).
