Official Content

Associates specific permissions to methods within an API object. These permissions control access and determine which users or roles are authorized to execute the methods.



View Syntax conventions


         Permission name used to identify which users or roles are authorized to execute the methods that are associated with that specific permission.


In an API object, there may be different methods that perform different tasks or actions. Some of these actions may require the user making the request to have specific permissions to access them.

For example, in a user management system, there may be methods that allow reading user information, creating new users, or modifying existing information.

This is where the concept of "specific permissions associated with methods" comes in with the SecurityPermission attribute.

When you use SecurityPermission for a particular method, you are setting a security requirement that must be met in order to execute that method. In other words, only those users or roles that have the specific permission associated with the method will be able to access and execute it. If a user does not have the required permission, the system will deny access to that particular method.


Suppose that you have followed steps 1 and 2 listed in HowTo: Define an API object with a security scheme

In the CustomerInfo method of the APICustomer object, which allows you to get the information of a specific customer, you want to define a permission called "ViewCustomerInfo". 

To do this, follow the first step mentioned in HowTo: Configure the API object security scheme. Clicking on the name of your Knowledge Base will open a screen as shown below:


Then click on MORE OPTIONS>Permissions>ADD and fill Name with ViewCustomerInfo.

When you click on confirm, the following information will appear under Permissions:


Next, you must assign the permission to the desired role, as shown in HowTo: Add a Permission to a Role using GAM.

You must then go back to the Service Source of the API object and define the SecurityPermission annotation as shown below:

    CustomerInfo(in:&CustomerId, in:&AccountId, in:&AccountPassword, out:&AccountBalance, out:&AccountStatus)
      => ShowCustomerInfo(&CustomerId, &AccountId, &AccountPassword, &AccountBalance, &AccountStatus);


  • In the sample, the value Authorization has been selected for the Integrated Security Level property in the API object.
  • It is unnecessary to set the Integrated Security Level property to Authorization. The annotation can also be used when the value Authentication is set.
  • The SecurityPermission annotation can be combined with the other API object notations.
  • The SecurityPermission annotation affects the method directly below it.


Since GeneXus 18 Upgrade 6.

See Also

GAM - Permissions Created by the User


Last update: April 2024 | © GeneXus. All rights reserved. GeneXus Powered by Globant