Users and roles

Create a role

POST/api/v1/admin/roles

Who can use this: Site adminsAs Markdown

A new role carries nothing until you give it permissions; then give the role to accounts. New roles are never protected, so they can be deleted later.

Parameters

Name	Where	What it is
name required	body	The role's name.e.g. auditor
description	body	What the role is for, in a few words.e.g. Reads the audit log

Good to know

A name already in use answers 409.

curl -s -X POST 'https://api.mailmasker.org/api/v1/admin/roles' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"auditor","description":"Reads the audit log"}'

use Mojo::Base -strict;
use Mojo::UserAgent;

my $ua  = Mojo::UserAgent->new;
my $res = $ua->post('https://api.mailmasker.org/api/v1/admin/roles',
    { Authorization => "Bearer $ENV{TOKEN}" },
    json => { name => 'auditor', description => 'Reads the audit log' })->result;
die $res->code, ' ', ($res->json('/error') // $res->message), "\n" unless $res->is_success;
print $res->body, "\n";

homelab-cli admin roles add auditor --description "Reads the audit log"

Response 201 Created

{
  "id": 4,
  "name": "auditor",
  "description": "Reads the audit log",
  "protected": 0,
  "created_at": "2026-11-03 21:42:10.123456-06",
  "permissions": []
}