Build with EventThing OAuth

EventThing OAuth gives your website a secure way to identify an EventThing user, understand which VTCs they can act on behalf of, and obtain a short-lived access token for a deliberately limited part of the EventThing API.

For most integrations, the goal is simple:

Who is this person?

and:

Which VTCs can they act on behalf of?

A VTC can add an Invite Us button to its own website. The visitor authorises with EventThing, your site receives the information allowed by the accepted scopes, the visitor chooses a VTC and one of that VTC's events, and the EventThing API creates the invitation.

OAuth identifies and authorises. The EventThing API still does the work.

OAuth does not replace the EventThing API. It gives your application a user-authorised token and a context object containing the data exposed by the accepted scopes.

What a successful authorisation gives you

A successful authorisation can return:

{
  "access_token": "et_oauth_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "profile vtcs events invites:create",
  "context": {
    "profile": {
      "id": "usr_7k2h9...",
      "name": "Bean",
      "avatar_url": "https://..."
    },
    "vtcs": [
      {
        "id": "vtc_onlytangs",
        "name": "OnlyTangs Haulage",
        "avatar_url": "https://...",
        "can_act": true,
        "events": [
          {
            "id": "evt_september_convoy",
            "name": "September Community Convoy",
            "starts_at": "2026-09-12T18:00:00Z"
          }
        ]
      }
    ]
  }
}

The data follows the way integrations actually use it:

User
  ↓
VTCs they can act for
  ↓
Events belonging to each VTC
  ↓
Create invitation

If events is not granted, the events property is omitted. If it is granted but a VTC has no applicable events, events is returned as an empty array.

Standard scopes

Scope	What it allows
`profile`	Basic EventThing user information, including display name and avatar
`vtcs`	VTCs the user belongs to and/or can act on behalf of
`events`	Eligible EventThing events, nested directly under each VTC
`invites:create`	Create an invitation on behalf of the authorised user and VTC

Normal OAuth integrations do not need the user's email address, Steam information or TruckersMP information.

OAuth user tokens are intentionally limited.

Creating an invitation is the only normal EventThing API action available to an OAuth user token. Wider API access remains available through VTC API tokens.

The Invite Us flow

[ Invite Us ]
      ↓
Continue with EventThing
      ↓
User reviews and authorises scopes
      ↓
Token + authorised context returned
      ↓
Choose VTC if more than one applies
      ↓
Choose one of that VTC's events
      ↓
POST /v1/invites
      ↓
Invitation appears normally in EventThing

If the user can act for only one VTC, you can normally skip the VTC selection step.

Once created, the invitation appears in the sender's Outgoing inbox and the recipient's Incoming inbox exactly like an invitation created directly through EventThing.

EventThing remains responsible for the invitation lifecycle and its own email/user notifications.

OAuth and API tokens are different

Credential	Represents	Intended use
OAuth user token	A specific user, accepted scopes and applicable VTCs	User-authorised Invite Us flows
VTC API token	One VTC and its configured API scopes	Wider programmatic VTC integration

OAuth extends the API with secure user delegation. It does not replace the normal VTC API model.

Next steps

Build an Invite Us integration — complete OAuth-to-invitation flow.
OAuth scopes — exact data exposed by profile, vtcs, events and invites:create.
OAuth tokens — token behaviour and how OAuth tokens differ from VTC API tokens.
OAuth security — PKCE, state, VTC validation and data minimisation.

Keep your website yours. Let EventThing handle the connection between VTCs.

Errors

Invite Us