Invitation Token

This token represents an invitation for a user to join a subscribable action. The subject (sub) is usually a conversation (CONV) action_id, but it may also be a community identity reference (@<id_tag>) for a community-membership invitation. Invitations enable controlled access to closed groups.

The invitation token must contain a subject (sub) field referencing the target and an audience (aud) field specifying the invited user. For other constraints see the Action Tokens. Like every action token it is content-addressed — see Content Addressing.

Purpose

An INVT grants one user access to a closed group, optionally pre-assigning the role they get on accepting, and carries the subject action (CONV) with it so the invitee can see what they are being invited to.

Required Fields

Field Required Description
iss Yes The inviter’s identity (must have moderator role on the subject, or be its creator)
aud Yes The invited user’s identity
sub Yes The CONV action_id (a1~...) or community identity (@<id_tag>) being invited to
t Yes “INVT” or “INVT:DEL”
c Optional Invitation metadata (role, message)

Subtypes

Subtype Description
INVT Create a new invitation
INVT:DEL Revoke an invitation

Content Structure

The optional content (c) field contains invitation metadata:

{
  "role": "member",
  "message": "Welcome to our project discussion!"
}
Property Type Required Description
role string No Role to assign when accepting: “observer”, “member”, “moderator”, “admin”
message string No Optional invitation message

Database Key

The database key for an invitation token is {type}:{sub}:{aud}, so only one active invitation exists per user per subject — see Database Keys.

Example:

  • Alice invites Bob to a CONV → Stored with key INVT:a1~conv123:bob.example.com
  • A new invitation to the same user replaces the previous one

Permission Requirements

Validated by the on_create hook on the inviter’s side: the inviter must either be the creator of the subject action or hold a moderator (or higher) role on it via an active SUBS. See Subscription Token roles for the full hierarchy.

Subject Delivery

INVT has deliver_subject=true behavior, meaning:

  • When an invitation is delivered, the subject action (e.g., CONV) is included
  • The invitee receives both the INVT and the CONV token
  • This allows the invitee to see conversation details before accepting
{
  "token": "eyJhbGciOi...INVT_TOKEN",
  "related": ["eyJhbGciOi...CONV_TOKEN"]
}

Federation Flow

Sending an Invitation

Moderator creates INVT token
         │
         ▼
┌─────────────────────────────┐
│ Validate permissions        │
│ - Check inviter has mod+    │
│ - Validate subject exists   │
└───────────┬─────────────────┘
            │
            ▼
┌─────────────────────────────┐
│ schedule_delivery()         │
│ - Deliver to invitee (aud)  │
│ - Include subject action    │
└───────────┬─────────────────┘
            │
            ▼
    Invitee receives INVT + CONV

Accepting an Invitation

The invitee accepts by creating a SUBS token referencing the CONV. Because an INVT exists, the subscription is auto-accepted. See SUBS auto-accept logic for details.

Revoking an Invitation

A moderator creates an INVT:DEL token, which is delivered to the invitee. The original INVT is marked deleted and can no longer be used to subscribe.

Invitation Lifecycle

An invitation is created (Active), then either consumed when the invitee subscribes, or revoked by the inviter via INVT:DEL:

┌──────────┐     Create      ┌──────────┐
│  None    │────────────────▶│  Active  │
└──────────┘                 └──────────┘
                                   │
                    ┌──────────────┴──────────────┐
                    ▼                             ▼
              SUBS created                    INVT:DEL
                    │                             │
                    ▼                             ▼
              ┌──────────┐                  ┌──────────┐
              │  Used    │                  │ Revoked  │
              └──────────┘                  └──────────┘

Example

User @alice.cloudillo.net invites @bob.cloudillo.net to a conversation:

Field Value
iss alice.cloudillo.net
aud bob.cloudillo.net
iat 2024-04-13T00:01:10.000Z
k 20240301
t INVT
sub a1~NAado5PS4j5+abYtRpBELU0e5OQ+zGf/tuuWvUwQ6PA=
c {“role”: “member”, “message”: “Join our project discussion!”}

Delivery includes both the INVT token and the referenced CONV token (see Subject Delivery above).

See Also