Skip to main content
Invites allow you to control user registration by requiring invite codes. This is useful for private instances or controlled access environments.

​
Enabling Invites

Invites must be enabled in your Zipline configuration: 
INVITES_ENABLED=true
INVITES_LENGTH=12  # Length of generated invite codes
If invites are enabled, users must provide a valid invite code during registration. Without invites enabled, registration may be open to anyone depending on your configuration.

​
Creating Invites

Administrators can create invite codes through the API: 
curl -X POST https://your-zipline.com/api/auth/invites \
  -H "Authorization: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expiresAt": "2024-12-31T23:59:59Z",
    "maxUses": 5
  }'

​
Invite Parameters

  • expiresAt - When the invite expires (ISO 8601 date string or “never”)
  • maxUses - Maximum number of times the invite can be used (optional)

​
Expiration Options

Set a specific expiration date: 
{
  "expiresAt": "2024-06-01T00:00:00Z"
}
Create an invite that never expires: 
{
  "expiresAt": "never"
}

​
Usage Limits

Limit invite to a specific number of uses: 
{
  "expiresAt": "never",
  "maxUses": 10
}
Create a single-use invite: 
{
  "expiresAt": "2024-12-31",
  "maxUses": 1
}

​
Managing Invites

​
List All Invites

Retrieve all invite codes: 
curl https://your-zipline.com/api/auth/invites \
  -H "Authorization: YOUR_TOKEN"
Response includes:
  • Invite code
  • Current usage count
  • Maximum uses
  • Expiration date
  • Creator information

​
Get Invite Details

Retrieve information about a specific invite by ID or code: 
curl https://your-zipline.com/api/auth/invites/{id_or_code} \
  -H "Authorization: YOUR_TOKEN"

​
Delete Invite

Revoke an invite code: 
curl -X DELETE https://your-zipline.com/api/auth/invites/{id} \
  -H "Authorization: YOUR_TOKEN"
Deleting an invite immediately invalidates the code. Users with this code will no longer be able to register.

​
Invite Validation

When a user registers with an invite code, Zipline automatically validates:
1

Code Existence

The invite code must exist in the database
2

Expiration Check

The current date must be before the expiration date (if set)
3

Usage Limit

The number of uses must be less than maxUses (if set)
4

Increment Counter

Upon successful registration, the usage counter is incremented

​
Web Invite Validation

You can validate an invite code without registering: 
curl https://your-zipline.com/api/auth/invites/web?code=INVITE_CODE
This endpoint returns invite information if valid, or indicates if the invite is:
  • Expired
  • Fully used
  • Non-existent

​
Registration with Invites

When registering with an invite code: 
curl -X POST https://your-zipline.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "password": "secure_password",
    "code": "INVITE_CODE_HERE"
  }'

​
Invite Validation Errors

Common error responses:
  • "Invites aren't enabled" - Invites are disabled in configuration
  • "Invalid invite code" - Code doesn’t exist, is expired, or is fully used

​
Invite Data Model

Each invite contains: 
{
  id: string,              // Unique identifier
  code: string,            // The invite code
  uses: number,            // Current number of uses
  maxUses: number | null,  // Maximum uses allowed
  expiresAt: Date | null,  // Expiration date
  inviterId: string,       // ID of admin who created it
  createdAt: Date,         // Creation timestamp
  inviter: {               // Creator information
    username: string,
    id: string,
    role: string
  }
}

​
Invite Code Generation

Invite codes are automatically generated using cryptographically secure random characters. The length is controlled by the INVITES_LENGTH configuration option. Default length: 12 characters 
INVITES_LENGTH=12
For higher security, increase the length: 
INVITES_LENGTH=24

​
Tracking Invite Usage

Monitor which invites are being used:
1

List Invites

Retrieve all invites to see usage counts
2

Check Logs

Server logs record when invites are used, including the new user’s username
3

Review Analytics

Cross-reference invite usage with user creation timestamps

​
Best Practices

Security Recommendations:
  • Set expiration dates on invites to limit their validity window
  • Use maxUses: 1 for invites sent to specific individuals
  • Regularly audit active invites and delete unused ones
  • Monitor invite usage in server logs
  • Rotate invite codes periodically for shared invites

​
Backup and Export

Invites are included in server exports and backups. When restoring from a backup, all invite codes and their usage statistics are preserved. See the Backups documentation for more information on including invites in your backup strategy.

Build docs developers (and LLMs) love

Get started for freeTalk to us