The 5-minute mental model¶

Read this once. The rest of the guide assumes you have it.

The shape of an integration¶

flowchart LR
    subgraph Org["Organization (formal, verified)"]
        Event["Event<br/><i>Sample Convention 2026</i>"]
    end

    subgraph You["Your integration"]
        Backend["Your backend<br/><i>holds tokens, calls API,<br/>receives webhooks</i>"]
    end

    Organizer((Organizer)) -->|connects with consent| Event
    Event -->|installation token| Backend
    Backend -->|GET /api/v1/events/.../participants| Revento[Revento API]
    Revento -.->|webhook: application.approved| Backend
    Participant((Participant)) -->|"Login with Revento"| Backend
    Participant -->|user token| Backend

You are the integration. You hold tokens, call the read API, receive webhooks. The platform is Revento. Organizers and participants are humans you don't authenticate yourself — Revento authenticates them and gives you a token.

Five things to internalize¶

1. Per-event binding, always¶

When an organizer connects your integration, they connect it to one specific event. Not to their account. Not to their organization. Not to all their future events.

If an organization runs ten events and wants your integration on all ten, the organizer connects it ten times. Each connection issues a separate token bound to one (event, organization, integration) tuple. Tokens from event A can't read event B even if both events belong to the same organization.

2. Two token types¶

Token type	Issued when	Acts as	Lifetime
Installation token	An organizer connects your integration to one of their events	"The integration, acting on behalf of this event"	Sliding 90-day refresh, hard cap 1 year from first issue
User token	A participant signs in via "Login with Revento" inside an event your integration is connected to	"This specific participant, in the context of this specific event"	Same lifetime curve as installation tokens

You'll usually have many of both. A typical integration connected to one event holds:

One installation token for the event
Zero or many user tokens — one per participant who has signed in via "Login with Revento"

The two token types cannot be used interchangeably. Calling a participant-scoped endpoint (/api/v1/me/...) with an installation token returns 403 user_token_required. Calling an event-scoped endpoint with a user token returns 403 installation_token_required. Same error message in reverse — pick the right token for the call.

3. Read-only¶

The framework has no write endpoints. You cannot create participants, update event metadata, post comments, send emails on behalf of an organizer, or modify any Revento-owned data.

If your integration needs to write something somewhere, it writes to its own storage (your database, a Google Sheet the organizer authorized you to write to, a Slack channel — anything outside Revento). The framework is neutral about what you do with the data once you've read it.

4. Webhooks carry the resource¶

When something changes in Revento (a new application is submitted, an event is published, an organizer reviews an application), Revento dispatches a webhook to the URL you registered. The payload includes the full resource snapshot at the moment the event occurred — you can act on it directly without round-tripping back to the API.

If you need related data not in the snapshot (e.g. you got application.approved and want the event metadata too), call the read API with your installation token.

Polling the API every minute also works, but it burns your rate-limit budget fast. Webhooks are the strongly recommended path.

5. Cascades and lifecycle¶

A connection is not forever. Several things invalidate tokens:

Organizer revokes the integration from their event → installation token + all derived user tokens for that event are invalidated immediately. You receive a data.deletion_required webhook with a 30-day deadline to delete cached data.
Event is unpublished → API calls continue working, but the event is no longer publicly visible. You receive an event.unpublished webhook if subscribed.
Organization loses formal status (rare but possible) → all integration connections across all of that org's events are invalidated; data.deletion_required fires per (event, organization) tuple.
You unpublish your integration (e.g. end-of-life it, remove it from the catalog) → every customer's tokens are invalidated and data.deletion_required webhooks fire for each (event, organization) tuple you'd been connected to.
Participant revokes "Login with Revento" access from their settings → their user tokens for your integration are invalidated; you receive a user.revoked_access webhook if subscribed.
Revento suspends your integration for compliance or security reasons → all your tokens invalidated immediately, you and affected organizers are notified.

Build with this in mind: any API call can fail with a token-revoked error, and your integration should handle that gracefully (stop polling, notify your operators, optionally re-prompt the user).

Things you might be wondering¶

"Can I get a list of all my installations?" Yes. GET /developer/integrations/{id}/installations lists every connection you have, by event and organization. Useful for dashboards and for cleaning up after disconnect cascades.

"Can I cache data?" Yes — that's much of the point. The contract is that you delete cached data within 30 days of a data.deletion_required webhook. Beyond that, cache as aggressively as you'd like.

"What happens if Revento is down?" Your installation tokens stay valid (we don't expire them on outage). Webhook delivery is queued and retried with the curve in Webhooks → retry behavior. API calls fail with normal HTTP errors during the outage; resume when we're back.

That's the model. The rest of this guide is detail on top.