--- title: "Security Scheme" slug: "security-scheme" description: "Enhance API access control with Traceable's Security Scheme. Learn how to define and manage role- and scope-based authorization for your APIs using dynamic auto-learn and user-defined mappings. Secure your application ecosystem against unauthorized access and BFLA attacks with flexible, traffic-aware access rules." updated: 2025-12-16T05:25:40Z published: 2025-12-16T05:25:40Z --- > ## Documentation Index > Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt > Use this file to discover all available pages before exploring further. # Security Scheme Security for your application ecosystem is not only about knowing APIs within it, but also ensuring that the right users with the right privileges can access these APIs. The Security Scheme in Traceable is a powerful role- and scope-based access control for APIs in your application ecosystem. It leverages both dynamic learning and manual definition to prevent unauthorized access to APIs. These schemes allow you to enforce accurate authorization rules based on your application and API architecture. This security scheme helps you enhance API security while ensuring authorized access and flexibility. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_catalog_security_scheme(1).png) Security Scheme ## What will you learn from this topic? By the end of this topic, you will understand: - What is a Security Scheme, and how can you use it to prevent unauthorized access to APIs. - What are the methods of security scheme configuration: Auto-learned and User-defined, and the difference between them. - How to configure role or scope mapping. --- ## What is a security scheme and how does it help? A Security Scheme is a guideline that secures your APIs against unauthorized access, data breaches, and broken function-level authorization (BFLA) attacks. It works in coexistence with [User Attribution](/v1/docs/user-attribution), which helps Traceable gather role and scope information from the incoming API traffic. Once you have set up user attribution, you can use the security scheme to enforce access control by defining roles and scopes, as well as permitted API endpoints for interaction. --- ## Before you begin Before setting up a Security Scheme, you must set up User Attribution. This is required as it allows Traceable to detect user roles and scopes from the incoming traffic. For information on setting this up, see [User Attribution](/docs/user-attribution). --- ## Understanding security scheme The Security Scheme is designed with the idea that every API call is evaluated based on who is making the request and what they are authorized to do. In Traceable, the Security Scheme page is a hub where you can manage roles and scopes across all API endpoints. It provides a comprehensive view of the authorized roles and scopes, along with their related endpoints, that you may have configured or that Traceable has detected from the incoming traffic. Using this page, you can define the security scheme for your endpoints that helps prevent unauthorized API interactions. To view the Security Scheme page, navigate to **Discovery** → **Settings** → **Security Scheme**. As mentioned above, you must configure [User Attribution](/v1/docs/user-attribution) to allow Traceable to extract role and scope information from the incoming traffic. Once you have configured user attribution, on the Security Scheme page, Traceable provides two modes of mapping roles and scopes: #### **Auto-learn mode** - **How it works** — If enabled, in this mode, Traceable automatically analyzes the incoming API traffic and maps roles, scopes, and endpoints dynamically. This method is useful if you wish to discover API access patterns without manual intervention. > [!NOTE] > Note > > Traceable auto-learns authenticated APIs only. - **Representation** — Traceable represents auto-learned roles, scopes, and endpoints using the ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_auto_learned_icon.png) icon. - **Retention** — For accuracy and relevance, Traceable automatically purges any auto-learned roles and scopes, along with their corresponding endpoints, if they are not observed for 7 consecutive days. - **Parent Hierarchy** — This method does not have a parent role or scope, as it is dynamic and learning-based. - **Endpoint Mapping** — Traceable automatically maps endpoints, identifying the role or scope. - **Conversion**— If you wish to retain a role or scope for long-term enforcement, you can convert it to a user-defined one. This ensures that Traceable retains it until you delete it. For information on enabling auto-learn and converting a role, scope, or endpoint to user-defined, see the [Enabling Auto-Learn](/v1/docs/security-scheme#enabling-autolearn) and [Converting Auto-Learned Schemes to User-Defined](/v1/docs/security-scheme#converting-autolearned-schemes-to-userdefined) sections, respectively. #### **User-defined mode** - **How it works** — In this mode, you can manually define the roles and scopes and the specific endpoints that the assigned users should be able to access. This method is useful if you wish to strictly enforce authorizations, especially in environments that contain sensitive data. - **Representation** — Traceable represents user-defined rules, scopes, and endpoints using the ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_user_defined_icon.png) icon. - **Retention** — Traceable retains these configurations until you delete them. - **Parent Hierarchy** — This method allows you to define a parent role or scope that inherits the access permissions granted to the child role. For example, the *Account Owner* role (Parent) inherits the permissions granted to the *Developer* role (Child). > [!NOTE] > Note > > The child role does not inherit access permissions granted to the parent role. - **Endpoint Mapping** — You can associate or map specific API endpoints that the role or scope can access. For information on creating a user-defined role or scope mapping, see [Creating a User-Defined Scheme](/v1/docs/security-scheme#creating-a-userdefined-scheme). --- ## Setting up a security scheme Traceable provides you with the flexibility to define Security Schemes according to your application architecture and business requirements. This flexibility is provided through Auto-Learn and User-Defined schemes. This section highlights the recommendations on when to use these modes, along with the corresponding steps. ##### **Recommendations** Traceable recommends using: - Auto-Learn mode when you do not have information on your traffic, and want Traceable to learn and create schemes dynamically. - User-defined schemes, when you wish to build access control based on the existing traffic insights. ### Enabling auto-learn mode Auto-Learn allows Traceable to dynamically learn roles, scopes, and their associated endpoints (authenticated) from the incoming traffic. To enable auto-learn for authorized roles or scopes, complete the following steps: ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_catalog_security_scheme_auto_learn(1).png) Enabling Auto-Learn 1. Navigate to the **Security Scheme** page. 2. From the page’s top right corner, **Environment** drop-down, select the environment for which you wish to enable auto-learn. By default, Traceable selects *All Environments*. 3. Select the **Authorized Roles** or **Authorized Scopes** tab according to your requirements. 4. Click the **Auto-learn** toggle to enable it. Traceable automatically learns the roles or scopes and the associated endpoints for the environment(s) in which you enabled the option, and shows them on the page. ### Creating a user-defined scheme You can define the roles, scopes, and endpoints that assigned users can access. To create a user-defined role or scope and select the endpoints, complete the following steps: 1. Navigate to the **Security Scheme** page. 2. From the page’s top right corner, **Environment** drop-down, select the environment for which you wish to create a user-defined scheme. By default, Traceable selects *All Environments*. 3. Select the **Authorized Roles** or **Authorized Scopes** tab according to your requirements. 4. Click the **+** icon. 5. In the **Create Role/Scope Mapping** window, complete the following: 1. Specify the **Role/Scope** name. 2. (Optional) Select the **Parent role/scope**. 3. Click **+ Add** to add accessible endpoints. In the**Select API Endpoint** window that appears, complete the following: 1. (Optional) Click the **Filter** (![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_filter_icon.png)) icon to filter endpoints or use the search field to search. 2. Click **Select** corresponding to the endpoints you wish to choose. 3. In the window’s bottom left corner, click **Review** and verify the selected endpoints. 4. Click **Add** once you have verified the selected endpoints. 4. Click **Create**. The following demo shows how to perform these steps in the Traceable platform. [Embedded content](https://demo.arcade.software/AO9VU5NcVG1csaLOcJmh) Traceable creates the role or scope and shows it on the page. --- ## Managing security schemes With your evolving application ecosystem and APIs, the roles and scopes also require management. Traceable provides you with the flexibility to manage the security schemes according to your requirements. Through this management, you can ensure that the access control is correct at all times. This section outlines the steps to convert auto-learned schemes to user-defined, update the schemes, and provides information on additional features available on the page. ### Converting auto-learned schemes to user-defined Traceable automatically purges any auto-learned roles, scopes, and endpoints if it does not observe any related traffic in 7 consecutive days. This helps maintain the accuracy and relevancy of data. While these auto-learned schemes are purged, the user-defined ones are stored until you delete them explicitly. If you wish to retain the auto-learned schemes in the Traceable platform, you can convert them to user-defined schemes. To convert an auto-learned role, scope, or endpoint to user-defined, complete the following steps: 1. Navigate to the **Security Scheme** page. 2. From the page’s top right corner, **Environment** drop-down, select the environment for which you wish to convert schemes. By default, Traceable selects *All Environments*. 3. Select the **Authorized Roles** or **Authorized Scopes** tab according to your requirements. 4. Depending on the role, scope, or endpoint you wish to convert, complete one of the following: - To convert a role or scope: 1. Click the **Ellipse** (![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_catalog_posture_events_ellipse_icon.png)) icon corresponding to the auto-learned role or scope, and click **Mark as User Defined**. > [!NOTE] > Note > > Converting a role or scope to user-defined does not automatically convert its endpoints. You must convert each endpoint manually. To do so, complete the below step. 2. In the confirmation window, click **Yes, Mark as User Defined**. - To convert an endpoint: 1. Click the **Ellipse** (![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_catalog_posture_events_ellipse_icon.png)) icon corresponding to the auto-learned role or scope and click **Edit**. 2. In the **Edit Role/Scope Mapping** window, **Endpoint** section, click the **Ellipse** (![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_catalog_posture_events_ellipse_icon.png)) icon and click **Mark as User Defined**. > [!NOTE] > Note > > Converting any auto-learned endpoint for a role or scope to user-defined automatically converts the associated role or scope to user-defined as well. 3. Click **Update**. The following demo shows how to perform these steps in the Traceable platform. It consists of two sections that show how you can convert a role or scope and an endpoint. [Embedded content](https://demo.arcade.software/IK23oESpeqYikgQFChML) ### Managing role and scope mappings To manage the mappings, click the **Ellipse** (![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_catalog_posture_events_ellipse_icon.png)) icon corresponding to a role or scope, and you can do the following: - **View** — View the mapping without making any changes. - **Edit** — Modify the mapping. If selected, you can modify all the fields and add or remove endpoints according to your requirements. - **Delete** — Delete the mapping from the Traceable platform. > [!NOTE] > Note > > A deleted mapping cannot be restored. - **Mark as User-Defined** (for Auto-Learned schemes only) — Convert auto-learned mappings to user-defined. You can do this to ensure that Traceable does not purge the mapping due to unavailable traffic. ### Additional features Apart from the above features, you can navigate to the respective roles/scopes tab and do the following: - **Search** — Use the search bar to search for schemes. - **Filter** — Click the **Filter** (![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_filter_icon.png)) icon to narrow down the schemes and/or endpoints based on their modes (auto-learn and user-defined). - **Bulk Delete** — Click the check box corresponding to the respective schemes and click **Delete** at the bottom of the page. > [!NOTE] > Note > > Deleted schemes cannot be restored.