Skip to content

Martini User Directory

Overview

The Martini User Directory is Martini's built-in identity provider that eliminates the need for external authentication systems. It stores user credentials securely within Martini itself, allowing you to create users and groups with just a few clicks. This gives you complete control over who can access your APIs and what they can do.

When to Use This

Use Martini User Directory when:

  • You need quick and simple authentication for local development and testing.
  • You want to secure small internal APIs without setting up an external provider.
  • You prefer managing users and groups yourself, regardless of the number of users.

Prerequisites

  • Martini Designer installed and running on your system

Users

A User in the Martini User Directory represents a person who can authenticate and access your APIs. Each user has a unique username, password, and can belong to one or more groups for permission management.

Getting Started

Follow these steps to create your first user:

  1. Open the Users & Groups Dialog
  2. In Martini Designer, locate the Users & Groups icon in the main toolbar
  3. If you can't find it, hover over each toolbar icon to see tooltips with their names

  4. Click the Users & Groups icon

  5. Navigate to Users Tab

  6. A dialog box opens with two tabs: Users and Groups
  7. The Users tab is selected by default

  8. Click the + (plus) button to add a new user

  9. Enter User Information Fill out these required fields:

Field What to Enter Purpose
Username john.doe Unique identifier for login (no spaces, use dots or underscores)
Email Address john.doe@company.com Contact information (must be valid email format)
Display Name John Doe Human-readable name shown in lists and interfaces
Password SecurePass123! Strong password for authentication (minimum 5 characters)
Enabled ✓ (checked) Leave checked to activate the account immediately

Important: Choose usernames carefully as they cannot be changed later. Use only letters, numbers, dots, and underscores.

  1. Skip Groups for Now
  2. Leave the Groups field empty

  3. You can add the user to groups later when needed

  4. Save the User

  5. Click Save to create the account
  6. The dialog closes and returns to the main interface

Expected Result: You'll see john.doe appear in the Users list when you reopen the Users & Groups dialog.

Configuration Properties

After creating a user, you can view and edit their information by selecting them from the Users list:

Property Example Value What It Controls
Username john.doe Login identifier (cannot be changed after creation)
Email Address john.doe@company.com Contact information and notifications
Display Name John Doe How the name appears in interfaces and reports
Password •••••••••••• Authentication credential (always hidden for security)
Enabled ✓ (checked) Account status - uncheck to temporarily disable access
Groups Managers, Developers Group memberships that determine permissions

System-Generated Properties (Read-only, used for OAuth2)

These values are automatically created and managed by Martini. Click the copy icon next to any field to copy its value:

Property Example Value What It's For
Access Token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Current authentication token for API calls
Expiration Date 2025-09-01 11:37 AM When the current token becomes invalid
Last Token Issue Date 2025-09-01 10:37 AM When the system last created a new token
Refresh Token def50200a1b2c3d4e5f6... Special token to get new access tokens
Total Tokens Issued 1 Total number of tokens created for this user

How It Works

The Martini User Directory supports two authentication methods. Here's exactly how to use each one:

Method 1: Basic Authentication (Username + Password)

Use this method when your API is configured for Basic Authentication:

  1. Get Credentials: Open Users & Groups → Select your user → Note the Username and Password
  2. Make API Request: In your HTTP client or application:
  3. Set Authentication Type to "Basic"
  4. Enter the username (e.g., john.doe)
  5. Enter the password (e.g., SecurePass123!)
  6. Send Request: Martini checks the credentials and grants access if they're valid and the account is enabled

Method 2: OAuth2 Authentication (Token-based)

Use this method when your API requires OAuth2 tokens:

  1. Get Token: Open Users & Groups → Select your user → Copy the Access Token value
  2. Make API Request: In your HTTP client or application:
  3. Set Authentication Type to "OAuth2"
  4. Paste the access token in the token field
  5. Handle Expiration: If you get an "expired token" error:
  6. Copy the Refresh Token from the user properties
  7. Use it to request a new access token
  8. Martini automatically tracks token usage and expiration

For step-by-step instructions on making authenticated requests, see Creating Requests in HTTP Client.

Why It Matters

Users form the foundation of API security. By managing them directly in Martini, you can quickly control who has access without configuring external providers.

Troubleshooting

When users can't access your APIs, here's how to diagnose and fix common issues:

Problem How You'll Know Most Likely Cause Solution
"Full authentication is required" error API returns 401 status Wrong username/password or disabled account Check credentials match exactly; verify account is enabled
"Access denied" error API returns 403 status User exists but lacks permissions Add user to appropriate group with required permissions
Token-related errors "Invalid token" or "Token expired" Expired or malformed OAuth2 token Copy fresh access token from user properties

Groups

A Group organizes users who need the same level of access to your APIs. Instead of setting permissions for each user individually, you create groups (like "Managers" or "Developers") and assign users to them. This makes permission management much simpler and less error-prone.

Getting Started

Here's how to create your first group and add users to it:

  1. Open the Users & Groups Dialog
  2. Click the Users & Groups icon in the main toolbar

  3. The dialog opens with Users and Groups tabs

  4. Switch to Groups Tab

  5. Click the Groups tab

  6. Click the + (plus) button to create a new group

  7. Name Your Group

  8. Enter a descriptive name like Managers, Developers, or API_Users
  9. Choose carefully - group names cannot be changed once created!

Warning: If you make a typo, you'll need to delete the group and create a new one with the correct name.

  1. Add Users to the Group
  2. Click the + button in the Users section
  3. Select users from the dropdown (e.g., John Doe from our previous example)

  4. You can add multiple users to the same group

  5. Save the Group

  6. Click Save to create the group
  7. The dialog closes automatically

Expected Result: You'll see Managers in the Groups list, and John Doe will show Managers in his Groups property when you view his user details.

Configuration Properties

When you select a group from the Groups list, you can view and modify these properties:

Editable Properties

Property Example Value What You Can Do
Name Managers View only - cannot be changed after creation
Users John Doe, Jane Doe Add or remove users by clicking + or - buttons

How It Works

Groups act as permission containers that you can use throughout Martini. Here's where and how to apply them:

Using Groups for API Security

  1. As API Scopes: When configuring API endpoints, you can select groups as authorized scopes. Only users in those groups will be able to access the protected endpoints.

    Example: Set Managers group as a scope, and only users in the Managers group can call that API.

    For detailed setup instructions, see Managing User Scopes.

  2. In Service Logic: Use Martini's built-in functions to check group membership programmatically within your services. You can verify if a user belongs to a specific group before allowing certain operations.

    For available functions and examples, see Martini User Group Functions.

Best Practices for Groups

  • Use Descriptive Names: Choose names that clearly indicate the group's purpose (API_Administrators, ReadOnly_Users)
  • Keep It Simple: Start with basic groups like Users and Admins, then add more specific ones as needed
  • Plan Ahead: Think about your permission structure before creating groups since names can't be changed

Why It Matters

Groups prevent permission management chaos by: - Reducing Repetition: Set permissions once per group instead of once per user - Minimizing Errors: Less configuration means fewer chances for mistakes - Simplifying Changes: Move users between groups instead of reconfiguring individual permissions - Improving Security: Consistent permission patterns across similar users

Troubleshooting

Here's how to resolve common group-related issues:

Problem How You'll Know What Went Wrong How to Fix It
User can't access API Gets "Access denied" error User not in required group Add user to the appropriate group through Users & Groups dialog
Need to rename group Typo in group name Group names are immutable Delete the group and recreate it with correct name (reassign users)
Users missing from group Expected users don't appear in group Users weren't properly added Edit the group and re-add the missing users

Helpful Resources