Docs Administration Guide

Mockarty Administration Guide

This guide covers everything an administrator needs to configure after the first launch of Mockarty. It assumes you have already installed and deployed Mockarty following the Installation & Deployment guide.

Table of Contents

  1. First Launch
  2. Authentication Configuration
  3. User Management
  4. System Roles
  5. Namespace Management
  6. Namespace Roles
  7. Assigning Users to Namespaces
  8. Email Notifications Setup
  9. Backup and Restore
  10. Cleanup Policies
  11. Audit Logs
  12. LLM / AI Assistant Configuration
  13. Security Best Practices

First Launch

When you start Mockarty for the first time, the following happens automatically:

  • Database migrations are applied, creating all required tables and indexes.
  • A default namespace called sandbox is created.
  • A built-in admin account is created with default credentials.

Default Credentials

Field Value
Username admin
Password admin

Warning: Change the default password immediately after your first login. Using default credentials in production is a critical security risk.

Accessing the Web UI

Open your browser and navigate to:

http://localhost:5770/ui/

You will see the login page. Enter the default credentials to log in.

Changing the Default Password

  1. Log in with admin / admin.
  2. Navigate to Settings (gear icon in the sidebar).
  3. Go to the Profile section.
  4. Click Change Password.
  5. Enter a new strong password (minimum 8 characters, including uppercase, lowercase, digits, and special characters).
  6. Click Save.

Authentication Configuration

Mockarty supports multiple authentication methods. By default, authentication is disabled for local development convenience.

Enabling Authentication

Set the following environment variable before starting Mockarty:

AUTH_ENABLED=true

Important: Always enable authentication in production environments. Without it, anyone with network access can manage your mocks and system settings.

Local Authentication (Default)

When no external identity provider is configured, Mockarty uses its built-in local authentication system.

Password requirements:

  • Minimum 8 characters
  • At least one uppercase letter
  • At least one lowercase letter
  • At least one digit
  • At least one special character

Account lockout:

  • After 5 consecutive failed login attempts, the account is temporarily locked for 15 minutes.
  • An administrator can unlock accounts manually from the Admin Panel.

OAuth 2.0 Setup

Mockarty supports OAuth 2.0 with Google, Yandex, and VK providers.

Google

Environment Variable Description
OAUTH_GOOGLE_ENABLED Set to true to enable
OAUTH_GOOGLE_CLIENT_ID OAuth client ID from Google Console
OAUTH_GOOGLE_SECRET OAuth client secret
OAUTH_GOOGLE_REDIRECT_URL Callback URL (e.g., https://your-domain.com/api/auth/oauth/google/callback)

Yandex

Environment Variable Description
OAUTH_YANDEX_ENABLED Set to true to enable
OAUTH_YANDEX_CLIENT_ID OAuth client ID from Yandex
OAUTH_YANDEX_SECRET OAuth client secret
OAUTH_YANDEX_REDIRECT_URL Callback URL

VK

Environment Variable Description
OAUTH_VK_ENABLED Set to true to enable
OAUTH_VK_CLIENT_ID OAuth client ID from VK
OAUTH_VK_SECRET OAuth client secret
OAUTH_VK_REDIRECT_URL Callback URL

When OAuth is enabled, the login page displays additional buttons for each configured provider.

LDAP / Active Directory

Mockarty can authenticate users against an LDAP or Active Directory server.

Environment Variable Description Example
LDAP_ENABLED Set to true to enable true
LDAP_URL LDAP server URL ldap://ldap.example.com:389
LDAP_BASE_DN Base distinguished name for user search dc=example,dc=com
LDAP_BIND_DN Bind DN for initial connection cn=admin,dc=example,dc=com
LDAP_BIND_PASSWORD Bind password secret
LDAP_USER_FILTER Filter to find users (use %s for username) (uid=%s)
LDAP_GROUP_BASE_DN Base DN for group search (optional) ou=groups,dc=example,dc=com
LDAP_GROUP_FILTER Filter to find group membership (member=%s)
LDAP_USE_TLS Use StartTLS true
LDAP_SKIP_TLS_VERIFY Skip TLS certificate verification (not recommended) false

When LDAP is enabled, users can log in with their directory credentials. On first login, a Mockarty account is created automatically with the User system role.

SAML SSO

Mockarty supports SAML 2.0 for Single Sign-On integration with enterprise identity providers (Okta, Azure AD, OneLogin, etc.).

Configuration is done through the Admin Panel:

  1. Navigate to Admin Panel > Authentication > SAML.
  2. Upload or paste the Identity Provider (IdP) metadata XML.
  3. Copy the Mockarty Service Provider (SP) metadata URL and register it with your IdP.
  4. Configure attribute mapping (email, display name, groups).
  5. Enable SAML authentication.

Two-Factor Authentication (2FA)

Mockarty supports two types of two-factor authentication:

TOTP (Time-based One-Time Passwords):

  • Works with any authenticator app (Google Authenticator, Authy, Microsoft Authenticator, etc.)
  • Users enable it from Settings > Security > Two-Factor Authentication.
  • A QR code is displayed for scanning with the authenticator app.
  • Recovery codes are provided for backup access.

Email codes:

  • One-time codes sent to the user’s registered email address.
  • Requires email notifications to be configured (see Email Notifications Setup).
  • Users enable it from Settings > Security > Two-Factor Authentication.

Enforcing 2FA:

Administrators can require 2FA for all users or specific roles:

  1. Navigate to Admin Panel > Authentication > 2FA Policy.
  2. Choose enforcement level:
    • Disabled — 2FA is optional for everyone.
    • Admin only — Only Admin role users must enable 2FA.
    • All users — Every user must enable 2FA on their next login.
  3. Click Save.

Users who have not yet configured 2FA will be prompted to set it up on their next login when enforcement is active.

User Management

Creating Users

  1. Navigate to Admin Panel > Users.
  2. Click Create User.
  3. Fill in the required fields:
    • Username — Unique login name.
    • Email — Email address (used for notifications and password resets).
    • Password — Initial password (user can change it later).
    • System Role — Select from Admin, Support, Auditor, or User (see System Roles).
  4. Click Create.

Setting Passwords and Emails

  • To reset a user’s password: Admin Panel > Users > (select user) > Reset Password.
  • To change a user’s email: Admin Panel > Users > (select user) > Edit > Email.
  • Password reset links can be sent via email if email notifications are configured.

Disabling / Enabling Accounts

Disabled accounts cannot log in, but their data and namespace assignments are preserved.

  1. Navigate to Admin Panel > Users.
  2. Find the user in the list.
  3. Click the toggle switch next to their name to disable or enable the account.

Deleting Users

  1. Navigate to Admin Panel > Users.
  2. Find the user in the list.
  3. Click Delete.
  4. Confirm the deletion.

Note: Deleting a user removes their account and all namespace role assignments. Mocks and other resources created by the user are preserved.

User Self-Registration

When OAuth or LDAP is enabled, users can register themselves by logging in through the external identity provider. A Mockarty account is created automatically with the User system role. The administrator can then assign namespace roles as needed.

System Roles

Mockarty has four system-level roles that determine what a user can access across the entire platform.

Role Descriptions

Admin
Full system access. Admins can manage all users, all namespaces, system settings, audit logs, backups, email configuration, LLM profiles, telemetry, and database health. This role should be limited to a small number of trusted people.

Support
Limited administrative access. Support users can view user accounts, reset passwords, view audit logs, and handle support-related tasks. They cannot change system settings, delete users, or access sensitive configuration.

Auditor
Read-only access to audit logs and system metrics. Auditors cannot modify any resources. In the sidebar, they see: Dashboard, Mocks (view only), Test Runs, Recorder, Fuzzing, Utils, Settings (view only), and Admin (audit logs only).

User
Standard user account. Permissions are determined entirely by namespace role assignments (see Namespace Roles). Users have no access to the Admin Panel.

Permissions Matrix

Capability Admin Support Auditor User
View Dashboard Yes Yes Yes Yes
Manage own profile Yes Yes Yes Yes
Access Admin Panel Yes Yes Partial No
Create / delete users Yes No No No
View user list Yes Yes No No
Reset user passwords Yes Yes No No
Disable / enable accounts Yes No No No
Manage system settings Yes No No No
Create / delete namespaces Yes No No No
View audit logs Yes Yes Yes No
Export audit logs Yes Yes Yes No
Manage backups Yes No No No
Configure email settings Yes No No No
Manage LLM profiles Yes No No No
View telemetry / metrics Yes No Yes No
Database health Yes No No No
Manage API tokens Yes No No No
View mocks (all namespaces) Yes No Yes No
Work with namespace resources Yes No No By role

Namespace Management

What Is a Namespace

A namespace is an isolated workspace within Mockarty. Each namespace contains its own:

  • Mocks and routes
  • Global, Chain, and Mock stores
  • API test collections and environments
  • Test run results
  • Recorder sessions
  • Fuzzing configurations
  • API tokens

Namespaces provide separation between teams, services, or environments. Resources in one namespace are invisible to users of another namespace (unless they have roles in both).

Creating Namespaces

Via Admin Panel:

  1. Navigate to Admin Panel > Namespaces.
  2. Click Create Namespace.
  3. Enter a name and optional description.
  4. Click Create.

Via Settings page:

  1. Navigate to Settings > Namespaces (visible to Admin users).
  2. Click Create Namespace.
  3. Enter a name and optional description.
  4. Click Create.

Naming Conventions and Best Practices

Choose a naming convention that fits your organization:

Strategy Example namespaces Best for
Per team backend-team, mobile-team, qa-team Small organizations
Per service payment-service, user-service, orders Microservice architectures
Per environment dev, staging, qa, demo Environment-based workflows
Combined payments-dev, payments-staging Large organizations

Tips:

  • Use lowercase names with hyphens (e.g., user-service).
  • Keep names short but descriptive.
  • Avoid generic names like test or temp for permanent namespaces.
  • Document your naming convention so all teams follow it consistently.

Default Namespace

The sandbox namespace is created automatically on first launch. It cannot be deleted. All users have access to the default namespace unless explicitly removed.

Deleting / Restoring Namespaces

  1. Navigate to Admin Panel > Namespaces.
  2. Find the namespace and click Delete.
  3. Confirm the deletion.

Warning: Deleting a namespace removes all mocks, stores, test collections, and other resources within it. This action is irreversible.

Namespace Roles

Within each namespace, users can have one of three roles that control what they can do with namespace resources.

Role Descriptions

Owner
Full control over the namespace. Owners can manage namespace settings, add or remove users, and perform all operations on resources (mocks, stores, collections, tests). Owners can also delete the namespace.

Editor
Can create, edit, and delete mocks, stores, collections, and run tests. Editors cannot manage namespace settings or add/remove users.

Viewer
Read-only access to all namespace resources. Viewers can browse mocks, view test results, and see store values, but cannot create, edit, or delete anything.

Namespace Capabilities Matrix

Capability Owner Editor Viewer
View mocks Yes Yes Yes
Create / edit / delete mocks Yes Yes No
Import mocks (OpenAPI, HAR, etc.) Yes Yes No
View stores Yes Yes Yes
Create / edit / delete stores Yes Yes No
View API test collections Yes Yes Yes
Create / edit / delete collections Yes Yes No
Run tests Yes Yes No
View test results Yes Yes Yes
Use API Tester Yes Yes No
View Recorder sessions Yes Yes Yes
Start / stop Recorder Yes Yes No
Configure Fuzzing Yes Yes No
View Fuzzing results Yes Yes Yes
Manage namespace API tokens Yes No No
Add / remove namespace users Yes No No
Change namespace settings Yes No No
Delete namespace Yes No No
Use Agent Chat Yes Yes Yes

Assigning Users to Namespaces

Adding a User to a Namespace

  1. Switch to the target namespace using the namespace selector in the sidebar.
  2. Navigate to Settings > Users.
  3. Click Add User.
  4. Select the user account from the dropdown list.
  5. Choose a role: Owner, Editor, or Viewer.
  6. Click Add.

Changing a User’s Namespace Role

  1. Navigate to Settings > Users within the target namespace.
  2. Find the user in the list.
  3. Click the role dropdown next to their name.
  4. Select the new role.
  5. The change takes effect immediately.

Removing a User from a Namespace

  1. Navigate to Settings > Users within the target namespace.
  2. Find the user in the list.
  3. Click Remove.
  4. Confirm the action.

Note: Removing a user from a namespace does not delete their account. They simply lose access to that namespace’s resources.

Email Notifications Setup

Email notifications enable password resets, 2FA code delivery, invite links, and test run notifications.

Enabling Email

Set the following environment variables:

Environment Variable Description Example
EMAIL_ENABLED Enable email notifications true
SMTP_HOST SMTP server hostname smtp.gmail.com
SMTP_PORT SMTP server port 587
SMTP_USERNAME SMTP authentication username noreply@yourcompany.com
SMTP_PASSWORD SMTP authentication password app-specific-password
EMAIL_FROM Sender email address noreply@yourcompany.com
EMAIL_FROM_NAME Sender display name Mockarty

Implicit TLS (Port 465)

If your SMTP server uses implicit TLS (typically on port 465), set:

SMTP_USE_IMPLICIT_TLS=true

For STARTTLS (typically on port 587), leave this unset or set to false.

Testing Email Configuration

  1. Navigate to Admin Panel > Email Settings.
  2. Click Send Test Email.
  3. Enter a recipient email address.
  4. Click Send.
  5. Verify the test email arrives in the recipient’s inbox.

Custom Email Templates

Mockarty uses built-in HTML templates for all email notifications. You can customize them:

  1. Navigate to Admin Panel > Email Templates.
  2. Select the template to customize (e.g., “Password Reset”, “2FA Code”, “Invite”).
  3. Edit the HTML template. Available variables are listed on the page.
  4. Click Save.
  5. Use Preview to see how the email will look.
  6. Use Reset to Default to restore the built-in template.

What Gets Sent

Event Email content
Password reset request Link to reset password (expires in 1 hour)
2FA code (email method) 6-digit verification code (expires in 5 minutes)
User invite Link to join Mockarty with pre-assigned role
Email verification Link to verify email address
Test run completion Summary of test results with pass/fail counts

Backup and Restore

Automatic Backups

Mockarty creates automatic backups every 48 hours. Backups are stored in the data directory.

Manual Backup

Via Admin Panel:

  1. Navigate to Admin Panel > Backup.
  2. Click Create Backup.
  3. Wait for the backup to complete.
  4. Click Download to save the backup file.

Via API:

GET /api/admin/backup/download

This returns a downloadable archive containing the full backup.

Restoring from Backup

Via Admin Panel:

  1. Navigate to Admin Panel > Backup.
  2. Click Restore.
  3. Upload the backup file.
  4. Confirm the restore operation.
  5. Wait for the process to complete. The application may restart.

Via API:

POST /api/admin/backup/restore

Upload the backup file as multipart form data.

What Is Included in a Backup

  • Complete database (all mocks, stores, users, namespaces, test results, audit logs)
  • Uploaded files (proto files, OpenAPI specs, etc.)
  • Configuration data

Docker Persistent Storage

When running Mockarty in Docker, mount a persistent volume for the data directory to preserve backups across container restarts:

docker run -v /host/path/data:/app/data mockarty:latest

Cleanup Policies

Cleanup policies control how long historical data is retained. Configuring these prevents the database from growing indefinitely.

Configuring Cleanup

Navigate to Admin Panel > Cleanup or Settings > Cleanup within a namespace.

Available Policies

Policy Description Default
Request logs retention How long to keep recorded request/response logs 30 days
Undefined requests retention How long to keep logs of unmatched requests 14 days
Test report retention How long to keep test run reports 90 days
Expired mock handling What to do with mocks that have passed their TTL Archive

Expired mock handling options:

  • Archive — Mark expired mocks as inactive. They stop matching requests but remain visible in the UI for reference.
  • Auto-delete — Permanently remove expired mocks after a configurable grace period.
  • Do nothing — Leave expired mocks as-is (not recommended for production).

Audit Logs

Audit logs provide a detailed record of all significant actions performed in the system.

What Is Logged

  • Authentication events — User logins (success and failure), logouts, 2FA challenges.
  • Mock operations — Create, update, delete, import, export.
  • Namespace changes — Create, delete, user role assignments.
  • Admin actions — User management, system settings changes, backup/restore.
  • API token usage — Token creation, deletion, and usage patterns.
  • Store operations — Global store modifications.

Viewing Audit Logs

  1. Navigate to Admin Panel > Audit Logs.
  2. Browse the chronological list of events.

Filtering

Use the filter controls at the top of the page:

  • User — Filter by specific user account.
  • Event type — Filter by action type (login, mock.create, namespace.delete, etc.).
  • Date range — Specify start and end dates.
  • Namespace — Filter by namespace (for namespace-scoped events).

Exporting Audit Logs

  1. Apply desired filters.
  2. Click Export.
  3. Choose format:
    • CSV — Comma-separated values, suitable for spreadsheet analysis.
    • JSON — Structured data, suitable for programmatic processing.
  4. The file downloads to your browser.

LLM / AI Assistant Configuration

Mockarty includes an AI assistant (Agent Chat) that helps users create mocks, troubleshoot issues, and explore the system using natural language.

Enabling the AI Assistant

Set the following environment variable:

ENABLE_LLM=true

Default Configuration

When enabled without additional configuration, Mockarty connects to a local Ollama instance:

Setting Default value
Provider Ollama
URL http://localhost:11434
Model qwen3:1.7b

Configuring LLM Profiles

You can configure multiple LLM profiles via the Admin Panel:

  1. Navigate to Admin Panel > LLM Profiles.
  2. Click Create Profile.
  3. Fill in:
    • Name — Display name for this profile.
    • Provider — Ollama, OpenAI, OpenRouter, or Claude.
    • URL — API endpoint URL.
    • API Key — Authentication key (if required by provider).
    • Model — Model identifier.
  4. Click Save.
  5. Set one profile as Default for all users.

Per-Namespace Rate Limits

To prevent excessive LLM usage, configure rate limits per namespace:

  1. Navigate to Admin Panel > LLM Profiles.
  2. Under Rate Limits, set:
    • Requests per minute per namespace.
    • Requests per day per namespace.
  3. Click Save.

Agent Chat

When the AI assistant is enabled, a floating chat button appears on every page of the Web UI. Users can:

  • Ask questions about how to use Mockarty.
  • Request mock creation using natural language descriptions.
  • Get help with JsonPath expressions, Faker functions, and conditions.
  • Troubleshoot mock matching issues.

Security Best Practices

Follow these recommendations to keep your Mockarty installation secure.

Immediate Actions After Installation

  1. Change the default admin password. The admin/admin credentials are publicly documented. Change the password before exposing the instance to any network.

  2. Enable authentication. Set AUTH_ENABLED=true. Without this, any user with network access can manage your system.

  3. Enable 2FA for admin accounts. Two-factor authentication adds a critical layer of protection for privileged accounts.

Network and Transport Security

  1. Use HTTPS. Set up TLS certificates (auto-generated or custom) to encrypt all traffic. Set COOKIE_SECURE=true (this is the default) to ensure session cookies are only sent over HTTPS.

  2. Keep SSRF protection enabled. The ALLOW_PROXY_TO_PRIVATE_IPS setting defaults to false, which prevents mock proxy mode from reaching internal network services. Do not change this unless you understand the risks.

  3. Restrict network access. Use firewalls or network policies to limit who can reach the Mockarty ports (5770 for HTTP, 5773 for gRPC coordinator).

Access Control

  1. Use namespace isolation. Assign each team its own namespace with appropriate roles. This prevents accidental interference between teams.

  2. Follow the principle of least privilege. Assign the lowest role that meets each user’s needs. Most users should have the User system role with Editor or Viewer namespace roles.

  3. Rotate API tokens regularly. API tokens provide programmatic access. Rotate them periodically and revoke tokens that are no longer needed.

  4. Review audit logs. Regularly check audit logs for unexpected activity, especially failed login attempts and admin actions.

Operational Security

  1. Keep Mockarty updated. Apply updates promptly to receive security fixes.

  2. Back up regularly. Ensure automatic backups are working and periodically verify that backups can be restored.

  3. Monitor system health. Use the health check endpoint (/health) and metrics endpoint (/metrics) to monitor the system’s status.

Environment Variable Summary

Variable Recommended value Purpose
AUTH_ENABLED true Enable authentication
COOKIE_SECURE true (default) HTTPS-only session cookies
ALLOW_PROXY_TO_PRIVATE_IPS false (default) Prevent SSRF via proxy mode
MCP_TLS_INSECURE_SKIP_VERIFY false (default) Verify TLS certificates for MCP

See Also

Previous
Quick Start (10 min)