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:
- 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.
- Select the OAuth 2.0 checkbox in the Authentication Type section
- In the Identity Provider dropdown, select Lonti
- 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.
-
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.
-
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
-
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
-
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
-
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
-
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:
-
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.
-
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 |
Related Resources
- How to Manage User Accounts - User administration guide
- How to Change Your Password for a Lonti User Account - Password management
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:
-
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. -
Assign users to groups: Add users to appropriate groups based on their access needs
-
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.
-
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 |
Related Resources
- REST API Scopes
- How to Manage User Groups - Group management guide
- Understanding Roles and Permissions for User Accounts - Permission system overview
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
- Create a REST API
- Configure a REST API's Security and Authentication
- Creating Workflows - (Including Inputs and Outputs)
- Using Workflow Nodes to perform mapping and processing of data
Getting Started
- In the workflow associated with your REST API operation, add an input property named
$attribute_claimsof typeobjectin the Input. - In the REST API Editor's Security Tab, ensure that your Identity Provider is set to Lonti Identity Provider for authentication.
- When the operation is invoked by an authenticated Lonti user, Martini will populate
$attribute_claimswith the user's claims (such as organization, groups, and custom attributes). - 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_claimsis 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. |
Related Resources
- Creating and modifying REST APIs
- REST API Security and Authentication
- Creating Workflows – Including Inputs and Outputs
Helpful Resources
- Creating and modifying REST APIs
- Creating Workflows – Including Inputs and Outputs
- REST API Security and Authentication
- REST API Scopes
- Lonti Account Organizations and Users
- Community Q&A: Martini Community Have a Question? Post or search it here.