Skip to content

REST API Security and Authentication

Overview

Martini's REST API security controls who can access your endpoints. You pick an authentication method (OAuth 2.0, Basic Authentication, or public access) and connect it to a user directory. This lets you secure APIs without building authentication from scratch.

When to Use This

Use REST API security when you need to:

  • Control who can access your API endpoints
  • Integrate with existing authentication systems
  • Provide different access levels for different users
  • Secure customer-facing or internal applications
  • Comply with security requirements for your organization

Prerequisites

  • Martini Designer installed and running on your system
  • Basic understanding of REST API concepts
  • A Martini Package
  • A REST API

Setup Your API

Configure Authentication

Set up authentication for your REST API in just a few steps:

  1. Open your REST API in Martini Designer

    Don't have one yet? Create a REST API first.

  2. Navigate to the Security tab in the REST API Editor

    💡 Tip: Look for tabs at the bottom of the REST API Editor.

  3. Choose your authentication type:

    Authentication Type Best For Setup Time
    None Health checks, public APIs 2 minutes
    Basic Authentication Internal tools, simple apps 5 minutes
    OAuth 2.0 Enterprise apps, mobile clients 10 minutes

  4. Select your identity provider (for OAuth 2.0 and Basic Authentication):

    Provider Best For Requirements
    Martini User Directory Self-contained setup, small teams Available on all plans
    Lonti Identity Provider Enterprise SSO, existing Lonti users Lonti account and paid plan required

    Check the Identity Providers section for more details.

  5. Configure API Scopes (optional) for role-based access control

    See API Scopes for detailed setup instructions.

  6. Save your configuration

Adding Operation-Specific Authentication

Override the default authentication and access control for specific API operations when you need different security levels for different endpoints.

Setting Operation Authentication Type

  1. Navigate to your API operation:

    • Go to the Operations tab in your REST API

    Note: Tabs are found at the bottom of the REST API Editor.

    • Expand the endpoint structure to find your specific operation
    • Click on the operation you want to customize

  2. Set operation authentication:

    • In the operation details, find the Authentication field, and click on the text input

    • Choose from the available options:

    • Default - Uses the API's configured authentication

    • Basic - Forces Basic Authentication for this operation only
    • OAuth 2.0 - Forces OAuth 2.0 for this operation only
    • None - Makes this operation publicly accessible

    Note: Basic Authentication and OAuth 2.0 will only appear as options if you have enabled them in the Security tab for your API.

Setting Operation Scopes

Control which users or groups can access this specific operation by setting operation-level scopes. These scopes work alongside your API-level authentication to provide fine-grained access control.

For detailed instructions on configuring operation-specific scopes, see Setting an Operation-specific Scope in the API Scopes documentation.

Testing Your Secured API

Test your secured API using Martini Designer's HTTP Client:

Before You Start

Make sure you have:

  • ✅ An API with authentication configured
  • ✅ Test user credentials from your chosen identity provider

Get Test Credentials

For Martini User Directory:

If you're using Martini User Directory as your identity provider:

  1. Click the Users & Groups 👥 icon in Martini Designer's main toolbar
  2. Navigate to the Users tab
  3. Select your test user
  4. Copy the required credentials:
    • For OAuth 2.0: Copy the Access Token 📋
    • For Basic Authentication: Copy the Username and Password 📋

🤔 No test users? See How to Add Users in Martini User Directory.

For Lonti Identity Provider:

If you're using Lonti Identity Provider as your identity provider, follow the testing instructions in Test Your API Setup with Lonti Identity Provider.

Run Your Test

  1. Right-click any operation in your REST API and select Invoke in HTTP Client

  2. Go to the Authentication tab and select your authentication method:

    • OAuth 2.0: Paste your access token
    • Basic Auth: Enter username and password

  3. Click Send 🚀

✅ Expected results:

  • Valid credentials return a 200 OK response
  • Invalid credentials return a 401 Unauthorized response
  • Missing permissions return a 403 Forbidden response

For more information about using the HTTP Client, see Creating Requests in Martini Designer's HTTP Client.

Authentication Types

None (Public Access)

No authentication required - anyone can access the API endpoints without credentials.

Getting Started

  1. Follow the Configure Authentication steps, selecting None as your authentication type
  2. For testing instructions, see Testing Your Secured API

✅ Expected result: Anyone can access your API without providing credentials.

When to Use This

Use this when you need:

  • Health check endpoints for monitoring systems
  • APIs secured by external systems (API gateways, proxies)
  • Development and testing environments where security isn't required

How It Works

When authentication is set to "None", Martini bypasses all authentication checks for incoming requests. The API processes requests immediately without validating credentials or checking user permissions.

Why It Matters

Public access removes authentication barriers for truly public resources while keeping your development workflow simple. This approach is essential for health checks and APIs that rely on external security layers.

Troubleshooting

Problem Detection Cause Fix Affected Versions
Unintended public access Security audit finds exposed endpoints Authentication mistakenly set to None Change authentication type to OAuth 2.0 or Basic All versions
External monitoring fails Health check endpoints return 401 errors Authentication required for monitoring Set health check endpoints to None authentication All versions

OAuth 2.0

OAuth 2.0 provides secure, token-based authentication that supports different flows based on your identity provider.

Getting Started

  1. Follow the Configure Authentication steps, selecting OAuth 2.0 as your authentication type and choosing your identity provider
  2. For testing instructions, see Testing Your Secured API with OAuth 2.0

✅ Expected result: API requests require valid OAuth tokens and return 2xx for authenticated users, 4xx for unauthorized requests.

Testing Your Secured API with OAuth 2.0

Martini User Directory

When testing an API with OAuth 2.0 Authentication with a user from the Martini User Directory, you will first need to get the access token for the user you want to use. Follow these steps:

  1. In Martini Designer, locate the icon in the main toolbar

    If you can't find it, hover over each toolbar icon to see tooltips with their names

  2. Click the User & Groups icon in the main toolbar

  3. Navigate to Users tab

  4. Click the user who wishes to access your APIs

    Note: To add users in Martini User Directory, see How to Add Users in Martini User Directory

  5. Copy the Access Token in the selected user's panel

  6. Follow the testing instructions in Testing Your Secured API

  7. When asked to choose an Authentication Type, select OAuth 2
  8. Enter the Access Token that you've copied
  9. Send your API request

✅ Expected result: API requests require and will return 2xx when valid OAuth tokens in the Authorization header, and return 4xx response codes otherwise.

Lonti Identity Provider

Check out the following articles to test out OAuth2 Implicit flow with Lonti Identity Provider:

Key Terms

Term Definition
Access Token A temporary credential that grants access to protected API endpoints
Password Flow OAuth flow where users authenticate with username/password to receive tokens
Implicit Flow OAuth flow optimized for client-side applications where tokens are returned directly

How It Works

OAuth 2.0 authentication works differently based on your identity provider:

Martini User Directory (Password Flow):

  1. Client includes token when sending API requests
  2. Martini verifies token on each request

Lonti Identity Provider (Implicit Flow):

  1. Client redirects user to Lonti authorization page
  2. User logs in and grants permissions
  3. Lonti redirects back with access token
  4. Client uses token for API requests
  5. Martini validates token with Lonti on each request

Why It Matters

OAuth 2.0 provides enterprise-grade security without exposing user passwords to your API. It enables single sign-on experiences, granular permissions, and secure integrations with external applications. The token-based approach also supports automatic expiration and revocation for enhanced security.

💡 Bellini Integration: When using OAuth 2.0 with Lonti Identity Provider, your REST API integrates seamlessly with Bellini apps for unified authentication across your application ecosystem.

Troubleshooting

Problem Detection Cause Fix Affected Versions
Token expired error API returns 401 with "token expired" message Access token has exceeded expiration time Have user request a new token using refresh token or re-authenticate All versions
Invalid scope error API returns 403 with "insufficient scope" Token lacks required permissions Request token with proper scopes or adjust API scope requirements v2.1+
Provider connection failed Authentication requests timeout Identity provider unreachable Check network connectivity and provider status All versions

Basic Authentication

Users authenticate with username and password credentials sent with each request.

Getting Started

  1. Follow the Configure Authentication steps, selecting Basic Authentication as your authentication type and choosing your identity provider
  2. For testing instructions, see Testing Your Secured API

✅ Expected result: API requests require username and password in the Authorization header.

To test your API with Basic Auth, first gather the credentials of your test user.

Follow these steps:

  1. In Martini Designer, locate the icon in the main toolbar

    If you can't find it, hover over each toolbar icon to see tooltips with their names

  2. Click the User & Groups icon in the main toolbar

  3. Navigate to Users tab

  4. Click the user who wishes to access your APIs

    Note: To add users in Martini User Directory, see How to Add Users in Martini User Directory

  5. Copy the Username and Password in the selected user's panel

For testing instructions, see Testing Your Secured API, making sure to select Basic Auth and input the copied credentials.

✅ Expected result: API requests require and will return 2xx when valid Basic Auth credentials in the Authorization header, and return 4xx response codes otherwise.

How It Works

Basic Authentication follows this process:

  1. Client sends credentials when sending request to the secured API
  2. Martini decodes the credentials
  3. Martini validates username/password against chosen identity provider
  4. Valid credentials allow request processing; invalid credentials return 401 error

Why It Matters

Basic Authentication provides straightforward security for internal tools and systems where simplicity is more important than advanced features. It's widely supported by all HTTP clients and doesn't require complex token management. However, credentials are sent with every request, making HTTPS essential.

Troubleshooting

Problem Detection Cause Fix Affected Versions
Authentication failed API returns 401 "Unauthorized" Wrong username or password Verify credentials against identity provider All versions
Frequent lockouts Users report account lockouts Too many failed authentication attempts Implement retry logic with backoff in client All versions

Identity Providers

Identity providers manage user authentication for your REST APIs. When you configure OAuth 2.0 or Basic Authentication, you connect to an identity provider that validates credentials and manages permissions. Martini offers two options: built-in user directory for self-contained setups, and Lonti's cloud services for enterprise environments.

Martini User Directory

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

For detailed setup instructions and user management features, visit the Martini User Directory documentation.

Lonti Identity Provider

Connect your Martini APIs to Lonti's identity system for secure authentication using existing user accounts, groups, and permissions. Lonti Identity Provider comes pre-enabled in your Martini instance—no setup or confguration required. Simply confgure your API security settings to use Lonti Identity Provider, and your existing Lonti users and groups become your API authentication system immediately.

Note: To retrieve user claims when using Lonti Identity Provider, add a $attribute_claim object property to the input of your workflow. For details and examples, see the Lonti Identity Provider documentation.

For detailed setup instructions and user management features, visit the Lonti Identity Provider.

Scopes

Martini Rest API scopes allow you to control which users or groups can access specific parts of your API. This feature makes it easy to manage permissions and enforce secure, role-based access across your endpoints.

See our API Scopes documentation for more details on how to set up and when to use it.

Advanced Authentication Concepts

Custom Authentication Using HTTP Filter Triggers

You can use HTTP filter triggers to implement custom authentication logic for your REST APIs if the built-in authentication methods are not suitable for your needs. For a detailed guide and examples, see Custom Authentication Using HTTP Filter Triggers.

Helpful Resources

Core Documentation

Identity Providers

Testing and HTTP Client

External Resources

Community Support