Invite Keys | Webstrates

Supported since: Webstrates 1.8.0

⚠️ Work in Progress: This page is a draft and is not yet complete. The information here may be subject to change.

Generating an Invitation
Using Invitations
Managing your Active Invitations
Advanced Usage

For webstrates owned by logged-in users, they can generate invitations to other users that will permanently grant read, read+write or admin permissions. Only logged-in users can use invites. Accepting such an invitation allows the receiving user to add themselves to the webstrate permission list with the permissions given in the invitation.

In comparison with Access Tokens, an invite can be sent to many users and only expires once its validity runs out - which happens if the sender is no longer an admin on the webstrate or if the invite expires. Also, the receiver does not become the sending user.

An invite can be generated by any logged in user with admin rights on a webstrate by using the invites API located in the webstrate.user.invites object.

Once generated, the invite key can be shared using whatever method - for example in the form of a URL in an email, over chat or social media, programmatically as a signal, …

Generating an Invitation

invites.create(…): This example code will create a read-only invitation with a 300 second expiry when run in the developer tools console:

await webstrate.user.invites.create({maxAge:300})

{ key: "c1d1a317e52ef4bd65b61aaccea778c03713475791d8905be25ef03cda30e678", webstrateId: "my-secret-webstrate", permissions: "r", expiresAt: "2025-08-08T15:54:20.304Z", createdAt: "2025-08-08T15:21:00.304Z", createdBy: {…}, ... }

The possible properties are maxAge (seconds to expiry) and permissions (“arw”).

Using Invitations

invites.check(key): It is possible to check the validity of an invitation and receive additional information about it if it is still valid.

try {
    let info = await webstrate.user.invites.check("c1d1a317e52ef4bd65…");
    // Do something with it here
} catch (ex){
    // Invalid invitation or other error
}

invites.accept(key): When accepting an invitation on a webstrate where the accepting user already has some permissions the permissions will be merged with the one from the invite.

try {
    await webstrate.user.invites.accept("c1d1a317e52ef4bd65…");
} catch (ex){
    // Invalid invitation or other error
}

HTTP Accept: Instead of using the invites.accept method to gain access to a webstrate using an invite, you can put the invite key in the query string. For the above example:

/my-secret-webstrate/?????=....

Managing your Active Invitations

invites.get(): A list of all currently active invites created by the currently logged-in user on the current webstrate can be generated using

await webstrate.user.invites.get();

[
  {
    "key": "c1d1a317e52ef4bd65b61aaccea778c03713475791d8905be25ef03cda30e678",
    "webstrateId": "my-secret-webstrate",
    "permissions": "r",
    "expiresAt": "2025-08-08T15:54:20.304Z",
    "createdAt": "2025-08-08T15:21:00.304Z",
    "createdBy": {…}
  }
]

invites.remove(key) Cancelling an invitation can be done using

try {
    await webstrate.user.invites.remove("c1d1a317e52ef4bd65…");
} catch (ex){
    // Could not delete it
}

Advanced Usage

All of the API methods default to working on the currently loaded webstrate. By adding the webstrate ID of another webstrate as an argument to any of the calls, however, they can be used to create, list, accept, etc. invites for any other webstrate located on the same server - with the same usage rules as above, naturally.

This is useful for creating applications where a portion of the application logic is on a read-only publically accessible webstrate and another portion (of the logic or data) is stored in personal webstrates owned by individual users.

For example this code will create a read+write invitation for another webstrate than the currently loaded one:

await webstrate.user.invites.create({permissions: "rw"}, "another-secret-webstrate");