Invitation Token

This token represents an invitation for a user to join a subscribable action, such as a conversation (CONV). Invitations enable controlled access to closed groups.

The invitation token must contain a subject (sub) field referencing the subscribable action and an audience (aud) field specifying the invited user. For other constraints see the Action Tokens.

Content-Addressing

This token is content-addressed using SHA-256:

  • The entire JWT token (header + payload + signature) is hashed
  • Action ID format: a1~{base64_hash}
  • Changing any field invalidates the action_id
  • See Content-Addressing & Merkle Trees for details

Immutability: Once created, an INVT token cannot be modified without changing its action ID.

Purpose

INVT tokens serve several important purposes:

  1. Access Control: Enable users to join closed/private groups
  2. Role Assignment: Pre-assign roles for invited users
  3. Discoverability: Notify users about groups they can join
  4. Subject Delivery: Include the subject action (CONV) with the invitation

Required Fields

Field Required Description
iss Yes The inviter’s identity (must have moderator+ role)
aud Yes The invited user’s identity
sub Yes The action_id being invited to (a1~...)
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}

Purpose: This key ensures that only one active invitation exists per user per subject. The key components are:

  • {type}: “INVT” (base type)
  • {sub}: Subject ID (what they’re invited to)
  • {aud}: Audience identity (who is invited)

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

The inviter must have at least moderator role on the subject action. See Subscription Token roles for the full role 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

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

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