Rest API 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.

🔒 Heads up: Rest API Scopes functionality is limited to paid plans only.

Usage Guide with Examples

Basic Authentication with Martini User Directory

This example demonstrates how to set up a product catalog API with basic authentication and the Martini User Directory for role-based access control.

Prerequisite Before setting up your REST API's security and authentication:

Create the following user groups:

User Group Name	Description
products.customer	Users who can only view product catalog
products.manager	Users who can view and modify product catalog

Add a user to each user group:

A customer user assigned to the products.customer group
A manager user assigned to the products.manager group

Step 1: Configure Authentication

See Security And Authentication - Identity Providers for more details on each 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 Basic checkbox in the Authentication Type section.
Notice that the Identity Provider becomes disabled and fixed to Martini User Directory. Basic authentication can only use the Martini User Directory as its identity provider.

Step 2: Define Scopes

Managing Scope Definitions

In the Scope Definitions section:

Add a scope definition by clicking the + icon on the right side.
Delete a scope definition by clicking the X icon on the right side.

Adding a Scope Definition

Click the + sign to open the Create a New Scope dialog box.
You can directly use your User Groups as scopes:
Click "Select User Group".
Add each of your created user groups.

Adding a Global Scope

Global scopes apply to all operations in your API:

Click on the Global Scopes text box.
Search for and select the scope you want to make global.
Add products.customer to Global Scopes so all authenticated users can view products.

Step 3: Configure API Operations

Go back to the Operations tab.
Create the following endpoints in your REST API:

Method	Endpoint	Description
GET	/products	List all products
POST	/products	Add new product

Setting an Operation-specific Scope

In our example, we only want users in the products.manager group to access the POST /products endpoint:

a. Expand the endpoint structure: /products > Operations > POST > Scopes

b. Click Scopes and select products.manager from scope definitions.

c. Leave Authentication set to Default to use the Basic authentication configured for the entire API.

Tip: You can override the authentication method for specific operations if needed.

Step 4: Testing

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

Test GET /products endpoint:
Right-click the GET operation under /products and select Invoke in HTTP Client.
Under the Authentication tab, select Basic Authentication.
Enter the username and password for your test user.
Click Send to execute the request.
Test POST /products endpoint:
Follow the same steps, but use credentials for a user in the products.manager group.
Users without manager access should receive a 403 Forbidden response.

Tip: Save these requests for future testing by clicking the Save icon in the main toolbar on the top left.

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

OAuth 2.0 with Lonti Identity Provider

This example demonstrates how to set up the same product catalog API as above, but using OAuth 2.0 authentication with Lonti Identity Provider.

Prerequisites

Before setting up your REST API Security:

Create the following user groups in your Lonti console:

Scope Name	Description
products.customer	Users who can only view product catalog
products.manager	Users who can view and modify product catalog

For testing purposes, assign your user account to these groups:

Join the products.customer group to test basic access
Join the products.manager group to test manager-level access

Note: When changing user groups, you must log out and log back in for your new permissions to take effect. This generates a new access token with the updated scope.

Step 1: Configure Authentication

See Security And Authentication for more details on Authentication Types and Identity Providers.

Navigate to the Security tab in the REST API Editor.
Select the OAuth 2.0 checkbox in the Authentication Type section.
In the Identity Provider dropdown, select Lonti.

Step 2: Define Scopes

Adding Scope Definitions

In the Scope Definitions section, click the + sign.
Enter the scope information from your Lonti application:

a. First scope:

Name: products.customer
Description: Users who can only view product catalog
Click "Add"

b. Second scope:

Name: products.manager
Description: Users who can view and modify a product catalog
Click "Add"

Adding a Global Scope

Click on the Global Scopes text box.
Select products.customer to allow all authenticated users to view products.

Step 3: Configure API Operations

Go back to the Operations tab.
Create your API endpoints:

Method	Endpoint	Description
GET	/products	List all products
POST	/products	Add new product

Setting an Operation-specific Scope

For the POST /products endpoint:

Navigate to /products > Operations > POST > Scopes.
Select products.manager to ensure only users with manager access can add products.

You may also set operation-specific authentication, see Security And Authentication.

Step 4: Testing

Test your secured API using Martini's built-in API Explorer - a web interface that makes testing OAuth APIs simple and intuitive.

Accessing the API Explorer for Testing

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 your 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
Navigate to your operation:

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

b. Look for and click on "POST /products"

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. This lets you enter your own data and interact with the endpoint before sending the request
Prepare your test data:

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

b. You can use the provided example or modify it as needed
Execute the request:

a. Click the "Execute" button

b. 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 your user account is in the products.manager group

Testing Different Permission Levels

To fully test your security setup:

Test with manager permissions: Use an account in the products.manager group - should succeed
Test with customer permissions: Use an account only in the products.customer group - should fail for POST operations
Test the GET /products endpoint: Should work for both customer and manager accounts due to the global scope

🔧 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.

Note: When changing user groups, you must log out and log back in for your new permissions to take effect. This applies to your own account or any user account you manage. This generates a new access token with the updated scope.

Scope Definitions

Scopes define what parts of the API users can access.

Scopes can be global (applied to the whole API) or operation-specific.
Manage scopes in the REST API's Security Tab.
Add, edit, or delete scopes via the UI.

Example Scope Table:

Scope Name	Description
products.read	Access to view products

Global Scopes

Global scopes are automatically applied to all operations in your API. They ensure that any user accessing any endpoint must have at least these basic permissions.

For example, if you set a products.customer scope as global, all operations (GET, POST, PUT, DELETE) will require users to have this scope, regardless of any additional operation-specific scopes you may configure.

Global scopes work alongside operation-specific scopes - users need both the global scope AND any operation-specific scopes to access a particular endpoint.

See the Usage Guide examples above for step-by-step instructions on adding global scopes.

Operation Scopes and Authentication

Each operation can have specific scopes.
Operations also have an Authentication property:
- Default: Uses the configured scheme from the Security Tab.
- Basic: Uses only basic authentication.
- OAuth 2.0: Uses only OAuth 2.0.
- None: No authentication required for this specific operation.

See the Usage Guide examples above for step-by-step instructions on adding operation-specific scopes and authentication.

Managing User Scopes

User scopes let you control access to API operations using your existing user groups, keeping security simple and aligned with your organization. For example, if you have a products.manager user group, you can use it as a scope so only managers can perform certain actions.

You can use user groups as scopes with both identity providers (listed below).

See Security And Authentication - Identity Providers for more details on each identity provider.

Martini User Directory

Using Martini User Directory allows to you select a user group directly from the user group list in Martini. You can just pick the group you want, and it will automatically be used as a scope for your API

In the Scope Definitions section, click the + sign to add a new scope
In the Create a New Scope dialog, click "Select User Group"
Choose from your existing user groups - each group you select becomes a scope with the same name
Repeat for each user group you want to use as a scope

This automatically creates scopes that match your user group names (like products.customer and products.manager).

📖 Try it yourself: See Add Scope for Martini User Directory to learn how to select user groups as scopes.

Lonti Identity Provider

When using Lonti Identity Provider, you can easily use your existing user groups from the Lonti console. You can just manually create scopes in Martini that match your Lonti user group names to enable secure, group-based access:

First, verify your user groups exist in the Lonti Console
Note the exact user group names (case-sensitive, including any dots or special characters)
In Martini's Scope Definitions section, click the + sign to add a new scope
Enter the scope name exactly as it appears in your Lonti user groups
Add a description and click "Add"
Repeat for each Lonti user group you want to use as a scope

⚠️ Important: The scope name in Martini must exactly match your Lonti user group name for authentication to work properly.

📖 Try it yourself: See Add Scope For Lonti Identity Provider to learn how to create scopes for Lonti user groups.

OpenAPI and Swagger Mapping

Martini automatically generates OpenAPI/Swagger documentation for your API security settings.

For details about authentication types and identity providers, see Security And Authentication.

Martini User Directory

When using Martini User Directory, your security settings map to standard Basic and/or OAuth2 security schemes.

Swagger (Under securityDefinitions)

"securityDefinitions": {
  "Basic": {
    "type": "basic"
  },
  "OAuth2Password": {
    "type": "oauth2",
    "tokenUrl": "http://localhost:35693/oauth/token",
    "flow": "password",
    "scopes": {
      "products.customer": "",
      "products.manager": ""
    }
  }
}

OpenAPI (Under securitySchemes)

"securitySchemes": {
  "Basic": {
    "type": "http",
    "scheme": "basic"
  },
  "OAuth2": {
    "type": "oauth2",
    "flows": {
      "password": {
        "tokenUrl": "http://localhost:35693/oauth/token",
        "scopes": {
          "products.customer": "",
          "products.manager": ""
        }
      }
    }
  }
}

Lonti Identity Provider

Scopes defined with the Lonti Identity Provider are translated as follows:

Swagger (Under securityDefinitions)

"securityDefinitions": {
  "Lonti": {
    "type": "oauth2",
    "authorizationUrl": "https://auth.lonti.com/oauth2/authorize",
    "flow": "implicit",
    "scopes": {
      "products.customer": "",
      "products.manager": ""
    }
  }
}

Per operation: This security configuration combines both the global scope (products.customer) and operation-specific scope (products.manager) from our Usage Guide examples above. This means your API users must have both scopes to access these operations with specific requirements.

"security": [{
  "Lonti": ["products.customer", "products.manager"]
}]

OpenAPI (Under securitySchemes)

"securitySchemes": {
  "Lonti": {
    "type": "oauth2",
    "flows": {
      "implicit": {
        "authorizationUrl": "https://auth.lonti.com/oauth2/authorize",
        "scopes": {
          "products.customer": "",
          "products.manager": ""
        }
      }
    }
  }
}

Per operation: This security configuration combines both the global scope (products.customer) and operation-specific scope (products.manager) from our Usage Guide examples above. This means your API users must have both scopes to access these operations with specific requirements.

"security": [{
  "Lonti": ["products.customer", "products.manager"]
}]

None (No Authentication)

For detailed information about when or how no authentication is used, see Security And Authentication.

OpenAPI/Swagger mapping: When API security is set to None, no securityDefinitions or securitySchemes properties are generated.

Per operation: Operations with authentication set to None will have an empty security property:

 "security" : [ ]