Skip to content

Lonti Identity Provider

Overview

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 configuration required. Simply configure your API security settings to use Lonti Identity Provider, and your existing Lonti users and groups become your API authentication system immediately.

đź”’ Heads up: This feature is limited to paid plans only.

When to Use This

When to Use Lonti Identity Provider

Use Lonti Identity Provider when you need:

  • Seamless single sign-on integration with Bellini apps across your application ecosystem
  • Enterprise single sign-on across multiple applications in your organization
  • To leverage existing Lonti users and groups you already have set up
  • Centralized user management handled outside of Martini

When to Use Martini User Directory

Alternatively, you can use Martini User Directory when you need:

  • API keys for system integration with APIs published in Martini
  • OAuth authentication with Martini users for custom applications or prototypes
  • Self-contained setup with everything managed within Martini
  • Authentication on the free tier

Requirements: Available on all plans

Prerequisites

  • Active Lonti account with paid plan
  • Users and groups properly configured in your Lonti organization

For complete setup instructions for Lonti accounts, organizations, and users, see Lonti Account Organizations and Users.

Setup Your API

To use Lonti users and groups for authentication, configure your REST API to use Lonti Identity Provider.

Configure Authentication

Configure your REST API to use Lonti Identity Provider:

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

    Note: Tabs are found at the bottom of the REST API Editor, just above the console.

  2. Select the OAuth 2.0 checkbox in the Authentication Type section
  3. In the Identity Provider dropdown, select Lonti
  4. Add group scopes : To use Lonti user groups for access control, add group names as scopes in the User Scopes field. For detailed instructions, see Managing User Scopes with Lonti Identity Provider.

Test Your Setup

Verify that authentication works correctly using the API Explorer:

đź’ˇ Note: Ensure the test user account is assigned to the appropriate groups in Lonti before testing, as users can only access operations that match their group memberships.

  1. Open the API Explorer:

    a. In the Martini Designer window, click Martini in the top-left menu bar

    b. Select Open API Explorer from the dropdown menu

    The API Explorer will open in a new browser tab.

  2. Sign in with a Lonti account:

    a. When the API Explorer opens, you'll see a login dialog box

    b. Select Lonti Account from the available login options

    c. Click the Login button

    d. A new page will open asking for your Lonti credentials - this is the official Lonti sign-in page

    e. Enter your username and password, then click Sign In

    f. After successful authentication, you'll automatically return to the API Explorer

  3. Select your API:

    a. Look for the "Select a spec" dropdown at the top center of the page

    b. Click the dropdown and find your REST API by name

    c. Select it from the list

  4. Test an operation:

    a. On the left sidebar, expand the "default" section

    b. Look for and click on your API operation

    c. The operation details will appear in the main panel

    d. Click the Try it out button on the right side to unlock the request form

  5. Execute the request:

    a. If your endpoint requires data in the request body, fill in the example values

    b. Click the "Execute" button

    c. The API Explorer will automatically handle OAuth authentication using your logged-in Lonti account

  6. Review the results:

    a. Check the response status code (should be 200-299 for success)

    b. Review the response body for your expected data

    c. If you get a 403 error, verify that the user account is active and has the required group memberships

🔧 Troubleshooting: If you get authentication errors, ensure you're logged into the API Explorer with a Lonti account that belongs to the correct organization and user groups.

Expected result: Users can authenticate with your Martini APIs using their Lonti credentials and execute operations within their scope/permissions.

Users

Users are the individual people who can authenticate with your Martini APIs using their Lonti credentials. Each user's organization membership and group assignments determine what they can access in your applications.

Getting Started

To use Lonti users for API authentication:

  1. Setup users in Lonti: Ensure your users are properly set up in your Lonti organization. For complete user management procedures including adding, removing, and configuring users, see Lonti Account Organizations and Users.

  2. Configure your API: Follow the steps in Setup Your API to configure your REST API to use Lonti Identity Provider and test authentication.

How It Works

Users authenticate with Martini through OAuth 2.0 flows or direct API key authentication. When a user logs in, Lonti issues a JWT token containing user identity, organization membership, and group assignments. Martini validates these tokens and maps the contained claims to internal authorization policies.

The best part? Lonti handles all the heavy lifting—password management, multi-factor authentication, and session lifecycle. Your users get one set of credentials that works across all Lonti-integrated services.

Why It Matters

No more forcing users to create yet another account. They can use their existing Lonti credentials to access your Martini APIs, which means less friction and happier users. Plus, you don't have to worry about password resets or account management—Lonti handles all that.

Troubleshooting

Problem Detection Cause Fix
User login fails Authentication returns invalid credentials error Account deactivated or password expired Reactivate account or reset password in Lonti
Missing permissions API returns 401 insufficient privileges User not assigned to required groups Add user to appropriate groups with necessary roles
Token validation fails API returns 403 invalid token JWT signature mismatch or expiration Verify Lonti integration configuration and token refresh

User Groups

Groups let you organize users and control what they can access in your APIs. Instead of setting permissions for each user individually, you create groups with specific permissions and add users to them.

Getting Started

To use Lonti user groups for API authentication:

  1. Configure groups in Lonti: Create groups that match your API access requirements (e.g., api.read, admin.write) in your Lonti organization. For complete group management procedures including creating, modifying, and organizing user groups, see Lonti Account Organizations and Users.

  2. Assign users to groups: Add users to appropriate groups based on their access needs

  3. Add groups as API scopes: Follow step 4 in Setup Your API - Configure Authentication to add your group names as scopes in the User Scopes field. For detailed scoping instructions, see Managing User Scopes with Lonti Identity Provider.

  4. Test group permissions: Verify that your user groups work correctly with your APIs using the testing steps in Setup Your API - Test Your Setup.

đź’ˇ Important: Ensure users are assigned to the correct groups in Lonti before testing, as users can only access API operations that match their group memberships.

Advanced testing: For a detailed example and step-by-step on how to manage user group scopes, see OAuth 2.0 with Lonti Identity Provider in the REST API Scopes guide.

Expected result: Users can only access API operations that match their group memberships, and groups function correctly as API scopes.

How It Works

Group Authentication Flow

Here's how groups work: when a user logs in, their group memberships get packed into their JWT token. Martini reads these group claims and matches them against your access policies to decide what the user can do.

The beauty of groups is that users can belong to multiple ones, and permissions stack up across all their memberships. This gives you flexible role-based access control without the headache of managing individual user permissions.

Groups as API Scopes

Your Lonti user groups can be directly used as scopes in Martini REST APIs for fine-grained access control. This means a user group like products.manager can control who has access to specific API endpoints.

When you configure your REST API security, you can map group names directly to API scopes:

  • Group products.manager → Scope for full product management

For detailed instructions on setting this up, see Managing User Scopes with Lonti Identity Provider.

Why It Matters

Groups save you tons of time. Instead of setting up permissions for each person individually, you define what a group can do once, then just add people to that group. Perfect for growing teams where you don't want to be constantly tweaking individual access settings.

Troubleshooting

Problem Detection Cause Fix
Group permissions not applied User cannot access expected resources Group membership not properly synced Refresh user session or verify group assignment
Group not found in token JWT missing expected group claims Group created after user's last login User must re-authenticate to receive updated group claims

Retrieving Lonti User Claims in Workflows

You can access Lonti user claims directly in your workflow by adding a $attribute_claims object property to the workflow input. This property will be automatically populated with the authenticated user's claims when the Lonti Identity Provider is enabled for the API operation.

Prerequisites

Getting Started

  1. In the workflow associated with your REST API operation, add an input property named $attribute_claims of type object in the Input.
  2. In the REST API Editor's Security Tab, ensure that your Identity Provider is set to Lonti Identity Provider for authentication.
  3. When the operation is invoked by an authenticated Lonti user, Martini will populate $attribute_claims with the user's claims (such as organization, groups, and custom attributes).
  4. You may then map these to output or do additional processing or conditions based on the user's claims.

Expected result: Your workflow can access user claims from $attribute_claims for authorization, personalization, or auditing purposes.

Note: $attribute_claims is only populated when the Lonti Identity Provider is enabled for the operation.

How It Works

The following table explains the available attributes in the $attribute_claims object and why you might use each one in your workflows or API integrations:

Claim Name Example Path in $attribute_claims Description Purpose / Why You Would Use It
client_id $attribute_claims.claims.client_id OAuth client/application ID Identifies the application making the request; useful for auditing and multi-app environments.
token_use $attribute_claims.claims.token_use Type of token (access, refresh, etc.) Distinguishes between access and refresh tokens for session management and security.
scope $attribute_claims.claims.scope Access scopes Defines what actions/resources the user can access.
issueTime $attribute_claims.issueTime Token issued-at time Used for auditing and token lifecycle management.
expirationTime $attribute_claims.expirationTime Token expiration time Ensures tokens are valid only for a set period (security).
issuer $attribute_claims.issuer Token issuer Verifies the source of the token for trust and compliance.

Helpful Resources