Skip to main content

​
Permission System

​
Get Permission Definitions

GET /api/servers/{serverId}/members/permissions
Get all available permission definitions organized by category. Public endpoint.

​
Response

​
categories
array
Array of permission categories
{
  "categories": [
    {
      "id": "control",
      "name": "Control",
      "description": "Server power and control",
      "permissions": [
        {
          "id": "control.start",
          "name": "Start Server",
          "description": "Start the server"
        },
        {
          "id": "control.stop",
          "name": "Stop Server",
          "description": "Stop the server"
        },
        {
          "id": "control.restart",
          "name": "Restart Server",
          "description": "Restart the server"
        }
      ]
    },
    {
      "id": "files",
      "name": "Files",
      "description": "File management",
      "permissions": [
        {
          "id": "files.read",
          "name": "Read Files",
          "description": "View and download files"
        },
        {
          "id": "files.write",
          "name": "Write Files",
          "description": "Create and edit files"
        },
        {
          "id": "files.delete",
          "name": "Delete Files",
          "description": "Delete files and directories"
        }
      ]
    }
  ]
}

​
Member Management

​
List Members

GET /api/servers/{serverId}/members
Authorization: Bearer {token}
List all members (subusers) of a server.

​
Path Parameters

​
serverId
string
required
Server UUID

​
Authentication

Requires server access and users.read permission.

​
Response

​
members
array
Array of member objects
[
  {
    "id": "member-1",
    "userId": "user-123",
    "user": {
      "id": "user-123",
      "name": "John Doe",
      "email": "john@example.com",
      "image": "https://..."
    },
    "permissions": [
      "control.start",
      "control.stop",
      "control.restart",
      "console.read",
      "console.write",
      "files.read"
    ],
    "createdAt": "2024-01-15T12:00:00Z",
    "updatedAt": "2024-01-15T12:00:00Z"
  }
]

​
Get Member

GET /api/servers/{serverId}/members/{memberId}
Authorization: Bearer {token}
Get detailed information about a specific member.

​
Path Parameters

​
serverId
string
required
Server UUID
​
memberId
string
required
Member UUID

​
Authentication

Requires server access and users.read permission.

​
Errors

  • 404 - Member not found

​
Update Member Permissions

PATCH /api/servers/{serverId}/members/{memberId}
Authorization: Bearer {token}
Content-Type: application/json
Update a member’s permissions.

​
Path Parameters

​
serverId
string
required
Server UUID
​
memberId
string
required
Member UUID

​
Authentication

Requires server access and users.update permission.

​
Request Body

​
permissions
array
required
Array of permission strings (at least one required)
{
  "permissions": [
    "control.start",
    "control.stop",
    "console.read",
    "console.write",
    "files.read",
    "files.write"
  ]
}

​
Response

Returns the updated member object.

​
Errors

  • 400 - Validation failed (permissions array must have at least one item)
  • 404 - Member not found

​
Remove Member

DELETE /api/servers/{serverId}/members/{memberId}
Authorization: Bearer {token}
Remove a member from the server.

​
Path Parameters

​
serverId
string
required
Server UUID
​
memberId
string
required
Member UUID

​
Authentication

Requires server access and users.delete permission.

​
Response

{ "success": true }

​
Errors

  • 404 - Member not found

​
Invitation Management

​
List Invitations

GET /api/servers/{serverId}/invitations
Authorization: Bearer {token}
List all pending invitations for a server.

​
Path Parameters

​
serverId
string
required
Server UUID

​
Authentication

Requires server access and users.read permission.

​
Response

​
invitations
array
Array of invitation objects (only pending, non-expired invitations)
[
  {
    "id": "inv-1",
    "email": "newuser@example.com",
    "permissions": ["control.start", "console.read"],
    "inviter": {
      "id": "user-123",
      "name": "Server Owner",
      "email": "owner@example.com"
    },
    "expiresAt": "2024-01-22T12:00:00Z",
    "createdAt": "2024-01-15T12:00:00Z"
  }
]

​
Send Invitation

POST /api/servers/{serverId}/invitations
Authorization: Bearer {token}
Content-Type: application/json
Send an invitation to a user to join the server.

​
Path Parameters

​
serverId
string
required
Server UUID

​
Authentication

Requires server access and users.create permission.

​
Request Body

​
email
string
required
Email address to invite
​
permissions
array
required
Permissions to grant (at least one required)
{
  "email": "newuser@example.com",
  "permissions": [
    "control.start",
    "control.stop",
    "console.read",
    "console.write"
  ]
}

​
Response

​
id
string
Invitation UUID
​
email
string
Invitee email
​
permissions
array
Granted permissions
​
token
string
Invitation token (for manual sharing)
​
acceptUrl
string
Complete acceptance URL
​
expiresAt
string
Expiration timestamp
​
createdAt
string
Creation timestamp
{
  "id": "inv-2",
  "email": "newuser@example.com",
  "permissions": ["control.start", "control.stop", "console.read", "console.write"],
  "token": "unique-invitation-token",
  "acceptUrl": "https://stellarstack.io/servers/invitation/unique-invitation-token",
  "expiresAt": "2024-01-22T14:00:00Z",
  "createdAt": "2024-01-15T14:00:00Z"
}

​
Errors

  • 400 - User already a member, or pending invitation already exists

​
Cancel Invitation

DELETE /api/servers/{serverId}/invitations/{invitationId}
Authorization: Bearer {token}
Cancel a pending invitation.

​
Path Parameters

​
serverId
string
required
Server UUID
​
invitationId
string
required
Invitation UUID

​
Authentication

Requires server access and users.delete permission.

​
Response

{ "success": true }

​
Errors

  • 404 - Invitation not found

​
User Invitation Handling

These endpoints are used by invited users to view and accept invitations.

​
Get Invitation Details

GET /api/servers/members/invitation/{token}
Get invitation details by token (for acceptance page). No authentication required.

​
Path Parameters

​
token
string
required
Invitation token

​
Response

{
  "id": "inv-1",
  "server": {
    "id": "server-uuid",
    "name": "My Minecraft Server"
  },
  "inviter": {
    "name": "Server Owner",
    "email": "owner@example.com"
  },
  "permissions": ["control.start", "console.read"],
  "expiresAt": "2024-01-22T12:00:00Z"
}

​
Errors

  • 400 - Invitation already used, declined, or expired
  • 404 - Invitation not found

​
Accept Invitation

POST /api/servers/members/invitation/{token}/accept
Authorization: Bearer {token}
Accept an invitation and become a server member.

​
Path Parameters

​
token
string
required
Invitation token

​
Authentication

Requires user to be logged in.

​
Response

{
  "success": true,
  "server": {
    "id": "server-uuid",
    "name": "My Minecraft Server"
  }
}

​
Errors

  • 400 - Already a member, already used/declined, expired, or user is the owner
  • 401 - Not logged in
  • 404 - Invitation not found

​
Decline Invitation

POST /api/servers/members/invitation/{token}/decline
Decline an invitation. No authentication required.

​
Path Parameters

​
token
string
required
Invitation token

​
Response

{ "success": true }

​
Errors

  • 400 - Already used or declined
  • 404 - Invitation not found

​
Get My Memberships

GET /api/servers/members/my-memberships
Authorization: Bearer {token}
Get all servers where the authenticated user is a member.

​
Authentication

Requires user to be logged in.

​
Response

[
  {
    "id": "member-1",
    "server": {
      "id": "server-1",
      "name": "Minecraft Server",
      "status": "RUNNING",
      "node": {
        "displayName": "US East 1",
        "location": {
          "name": "New York"
        }
      }
    },
    "permissions": ["control.start", "console.read"],
    "createdAt": "2024-01-15T12:00:00Z"
  }
]

​
Get My Pending Invitations

GET /api/servers/members/my-invitations
Authorization: Bearer {token}
Get all pending invitations for the authenticated user.

​
Authentication

Requires user to be logged in.

​
Response

[
  {
    "id": "inv-1",
    "token": "invitation-token",
    "server": {
      "id": "server-1",
      "name": "Minecraft Server"
    },
    "inviter": {
      "name": "Server Owner"
    },
    "permissions": ["control.start", "console.read"],
    "expiresAt": "2024-01-22T12:00:00Z",
    "createdAt": "2024-01-15T12:00:00Z"
  }
]

​
Common Permission Nodes

Here are commonly used permission nodes:

​
Control

  • control.start - Start the server
  • control.stop - Stop the server
  • control.restart - Restart the server
  • control.kill - Force kill the server

​
Console

  • console.read - View console output
  • console.write - Send commands to console

​
Files

  • files.read - View and download files
  • files.write - Create and edit files
  • files.delete - Delete files
  • files.archive - Create archives

​
Backups

  • backups.read - View backups
  • backups.create - Create backups
  • backups.restore - Restore backups
  • backups.delete - Delete backups
  • backups.download - Download backups

​
Settings

  • settings.read - View server settings
  • settings.update - Modify server settings
  • settings.rename - Rename server
  • settings.reinstall - Reinstall server

​
Users

  • users.read - View members
  • users.create - Invite members
  • users.update - Update member permissions
  • users.delete - Remove members

Build docs developers (and LLMs) love

Get started for freeTalk to us