Build an Invite Us integration

This guide covers the complete flow from an Invite Us button on your website to an invitation being created through the EventThing API.

Start authorisation

Generate a cryptographically random state, a PKCE code_verifier, and its SHA-256 code_challenge.

GET https://auth.tmpeventthing.com/oauth/authorize
    ?client_id=et_app_your_client_id
    &redirect_uri=https%3A%2F%2Fexample.com%2Feventthing%2Fcallback
    &response_type=code
    &scope=profile%20vtcs%20events%20invites%3Acreate
    &state=YOUR_RANDOM_STATE
    &code_challenge=YOUR_CODE_CHALLENGE
    &code_challenge_method=S256

The user reviews access

EventThing authenticates the user and shows the requested scopes.

For a normal Invite Us integration:

profile
vtcs
events
invites:create

Exchange the code

Verify state, then exchange the authorisation code using the original PKCE verifier.

curl --request POST \
  --url https://api.tmpeventthing.com/v1/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code' \
  --data 'client_id=et_app_your_client_id' \
  --data 'code=AUTHORIZATION_CODE' \
  --data 'redirect_uri=https://example.com/eventthing/callback' \
  --data 'code_verifier=YOUR_ORIGINAL_CODE_VERIFIER'

The successful response contains the access token, accepted scopes and EventThing context.

Use the returned VTC context

When events is accepted, each applicable VTC contains its own events:

{
  "context": {
    "vtcs": [
      {
        "id": "vtc_onlytangs",
        "name": "OnlyTangs Haulage",
        "can_act": true,
        "events": [
          {
            "id": "evt_123",
            "name": "September Community Convoy",
            "starts_at": "2026-09-12T18:00:00Z"
          }
        ]
      }
    ]
  }
}

If only one VTC is available, select it automatically. If several are available, let the visitor choose one before showing that VTC's events.

Create the invitation

POST /v1/invites
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "acting_vtc_id": "vtc_onlytangs",
  "event_id": "evt_123",
  "invited_vtc_id": "vtc_your_vtc"
}

EventThing verifies that the token has invites:create, the user can still act for acting_vtc_id, and the selected event belongs to that VTC.

Never trust an arbitrary VTC ID supplied by the browser.

Done

The invitation is now a normal EventThing invitation.

It appears in the sender VTC's Outgoing inbox and the invited VTC's Incoming inbox. EventThing handles its own notifications and later invitation lifecycle communication.

Introduction

scopes