Authentication

Use these helpers to resolve ranks and permissions. Use them for tag-based admin checks too.

local Sphere = script:FindFirstAncestor("Sphere")
local API = require(Sphere.Core.API)

---

GetPermissions

Returns the permissions for a given rank, or all ranks and their permissions if no rank is provided.

API.PermissionTable must exist or this will error.

Example

--//Get permissions for a specific rank
local permissions = API.GetPermissions("Moderator")
if permissions then
    for permission, granted in permissions do
        print(`Moderator - {permission}: {granted}`)
    end
end

--//Get all ranks and their permissions
local all = API.GetPermissions()
for rank, permissions in all do
    for permission, granted in permissions do
        print(`{rank} - {permission}: {granted}`)
    end
end

Annotation

API.GetPermissions(
    Rank: string?
): {[string]: boolean} | {[string]: {[string]: boolean}} | nil

Input

Rank String? • Optional

The rank key to look up. If omitted, all ranks and their permissions are returned.

Output: Rank Provided

Returns {[string]: boolean}

A map of permission keys to their granted state for the specified rank.

Returns nil if the rank does not exist in API.PermissionTable.

Output: No Rank Provided

Returns {[string]: {[string]: boolean}}

A map of every rank key to its permissions map.

---

CheckPermission

Checks if a user has a permission key.

API.PermissionTable must exist or all permission checks will return false.

Example

local Players = game:GetService("Players")
local UserId = 1

--//Using a UserId
if API.CheckPermission(UserId, "Kick") then
    print(`Player with the UserId {UserId} can kick!`)
end

--//Using a Player instance
local player = Players:GetPlayerByUserId(UserId)
if player and API.CheckPermission(player, "Kick") then
    print(`{player.Name} can kick!`)
end

Annotation

API.CheckPermission(
    Player: number | Player,
    Permission: string
): boolean

Input

Player Number | Player • Required

The player to check. Accepts either a UserId or a Player instance.

Permission String • Required

The permission key to check against. Names are matched exactly, see Permissions.

Output

Returns Boolean

Returns true if the player holds a rank that grants the requested permission. Returns false if the player has no rank, if API.PermissionTable is missing the rank entry, or if the permission is not granted.

---

GetRank

Resolves the highest priority rank for a user. This reads Settings.Ranks.

Ranks and groups are cached per UserId. Clear caches if ranks change at runtime.

Example

local Players = game:GetService("Players")
local UserId = 1

--//Using a UserId
local rankId = API.GetRank(UserId)
if rankId then
    print(`{UserId} has the rank {rankId}`)
end

--//Using a Player instance
local Player = Players:GetPlayerByUserId(UserId)
if Player then
    local rankId = API.GetRank(Player)
    if rankId then
        print(`{Player.Name} has the rank {rankId}`)
    end
end

Annotation

API.GetRank(
    Player: number | Player
): string?

Input

Player Number | Player • Required

The player to resolve. Accepts either a UserId or a Player instance.

Output

Returns String?

Returns the rank key string with the highest Priority that the player qualifies for. Returns nil if the player does not qualify for any rank in Settings.Ranks.

---

IsAdmin

Checks if the player has the sphere.admins tag.

This only works for players currently in the server.

Example

local Players = game:GetService("Players")
local UserId = 1

--//Using a UserId
if API.IsAdmin(UserId) then
    print(`{UserId} is an admin`)
end

--//Using a Player instance
local player = Players:GetPlayerByUserId(UserId)
if player and API.IsAdmin(player) then
    print(`{player.Name} is an admin`)
end

Annotation

API.IsAdmin(
    Player: number | Player
): boolean

Input

Player Number | Player • Required

The player to check. Accepts either a UserId or a Player instance.

Output

Returns Boolean

Returns true if the player has a rank. Returns false if the player does not have a rank or is not present in the current server.

---

GetAvailableAdmins

Returns all admins currently in the server. Admins are players tagged sphere.admins.

Example

local Count, Admins = API.GetAvailableAdmins()

print(`There are {Count} admins available`)

for _, player in Admins do
    print(player.Name)
end

Annotation

API.GetAvailableAdmins(): (Count: number, Players: {Player})

Output: Admins Present

Count Number

The total number of admins currently in the server.

Players {Player}

A table of Player instances for each admin found.

Output: No Admins Present

Count Number

Returns 0.

Players {Player}

Returns an empty table.