invite_create

Create an invite code. In invite mode, a new user joins by sending the code as invite_code when they authenticate.

Request

{ "cmd": "invite_create", "max_uses": 5, "expires_in": 604800 }

Field	Type	Required	Description
max_uses	integer	No	How many people can redeem the code, from 0 to 1000. 0 means unlimited. Default 1.
expires_in	integer	No	Seconds until the code expires, up to 2592000 (30 days). Omit it or send 0 for a code that never expires.

Response

{
  "cmd": "invite_create",
  "invite": {
    "code": "3F9A1C7E52B4",
    "max_uses": 5,
    "uses": 0,
    "created_by": "USR:local_bob",
    "created_at": 1767225600.123,
    "expires_at": 1767830400.123
  }
}

code is 12 uppercase hexadecimal characters. expires_at is in Unix seconds, or null if the code never expires. The invite is recorded in the audit log. Nobody else is notified.

To share the code as a link, use https://<server host>/invite/<code>. See invite pages.

Invites can be created in any mode, but the server only reads invite_code in invite mode.

Permissions

Requires create_invite. The default user role has it, so ordinary members can create invites unless you remove it from that role. Listing and deleting invites needs manage_access, so a member can’t delete an invite they made. A user in timeout gets a rate_limit frame instead.

Errors

val	When
max_uses must be 1000 or less	max_uses is over 1000.
expires_in must be 30 days or less	expires_in is over 2592000.
Unable to generate an invite code	The server couldn’t find an unused code.
Unable to save invite	The server couldn’t save the invite.

A negative or non-integer max_uses or expires_in returns the schema validator’s message.

See also

• invite_list
• invite_delete