Why Do I Get an Access Denied Error for an API Method Call?

Symptoms

During application runtime, one of these exceptions occurs:

Access Denied. This action requires access right of 'Mark Automatic Work Item Completion'
Access Denied. This action requires access right of 'Allow to execute QueryDatabase() and QueryDatabaseEx()'
Access Denied. This action requires access right of 'Save or Remove Temporary File'

Cause

This exception occurs under these conditions:

  • AgilePoint NX OnPremises or AgilePoint NX PrivateCloud.
  • In the AgilePoint Server netflow.cfg file, trustedAuthorization is set to False.

    By default, trustedAuthorization is set to True.

  • One of these API methods executes, but the associated access right is deselected (disabled) for all roles assigned to the API authentication account:
    Method NameAccess ControlDescription
    CompleteProcedure()Mark Automatic Work Item CompletionIf trustedAuthorization is set to False, and the Mark Automatic Work Item Completion access right is deselected for all roles assigned to the API authentication account, this account can not make API method calls for Complete Procedure.
    QueryDatabase()Allow to Execute QueryDatabase() and QueryDatabaseEx()If trustedAuthorization is set to False, and the Allow to Execute QueryDatabase() and QueryDatabaseEx() access right is deselected for all roles assigned to the API authentication account, this account can not make API method calls for Query Database.
    QueryDatabaseEx()Allow to Execute QueryDatabase() and QueryDatabaseEx()If trustedAuthorization is set to False, and the Allow to Execute QueryDatabase() and QueryDatabaseEx() access right is deselected for all roles assigned to the API authentication account, this account can not make API method calls for Query Database (Extended Method).
    SaveTemporaryFile()Save, Remove Temporary FileIf trustedAuthorization is set to False, and the Save, Remove Temporary File access right is deselected for all roles assigned to the API authentication account, this account can not make API method calls for Save Temporary File.
    RemoveTemporaryFile()Save, Remove Temporary FileIf trustedAuthorization is set to False, and the Save, Remove Temporary File access right is deselected for all roles assigned to the API authentication account, this account can not make API method calls for Remove Temporary File.

There are 2 ways to resolve this issue. You can either turn on trustedAuthorization, or you can enable the necessary access controls for a role associated with the API authentication account. It is not necessary to do both procedures.

Resolution Option 1: Turn on trustedAuthorization

To turn on trustedAuthorization, do this procedure, do the procedure in this topic.

How to Start

  1. On the AgilePoint Server machine, in a text editor, open the file netflow.cfg.

Procedure

  1. In the trustedAuthorization attribute, change the value to True.
    Field NameDefinition

    trustedAuthorization
    Description:
    Specifies whether API calls are trusted. If this setting is turned off, API calls that can pose special security risks require additional access rights for authorization.

    By default, this setting is configured as True (turned on). However, if your organization does not use APIs to access AgilePoint NX, or you want to restrict the access these specific methods due to security risks, you can configure this setting to False.

    Allowed Values:
    • True - The API authentication account does not require a role with special access controls for any API methods, other than the access controls that are normally required to make API calls.

      This setting means that API calls are made from a trusted system.

    • False - These API methods are restricted:
      • Complete Procedure
      • Save Temporary File
      • Remove Temporary File
      • Query Database
      • Query Database (Extended)

      ​If trustedAuthorization is set to False, these methods can be enabled individually with access controls. For complete information, including settings, access controls, and troubleshooting, refer to Why Do I Get an Access Denied Error for an API Method Call?.

    Default Value:
    True
    Example:
    <server trustedAuthorization="False" ... />

Resolution Option 2: Enable Access Controls

To enable the access rights for the API methods that are restricted with trustedAuthorization is turned off, do the procedure in this topic.

Figure: Configure Access Rights > Process tab

Configure Access Rights Process tab
Figure: Configure Access Rights > Application Bulider tab

Configure Access Rights Application Bulider tab

Good to Know

  • The appropriate access rights must be enabled for a role that is associated with the API authentication account. You can either change an existing role, or you can create a role specifically for this purpose, and then add the role to the API user. This procedure assumes you want to add this access control to an existing role.

    For more information, refer to Roles.

How to Start

  1. In the Manage Center, click Access Control > Roles.
  2. On the Roles screen, select a role associated with the API authentication account, and click Expand.
  3. Click Edit Edit icon.
  4. Click the Access Rights tab.

Procedure

  1. Do one or more of these procedures to enable the access controls you want:
    • To enable the Complete Procedure method:
      1. Click the Process tab.
      2. Select Mark Automatic Work Item Completion.
        Field NameDefinition

        Complete System Activities (Automated Tasks)
        Description:
        Specifies whether the Complete Automatic Work Item and Complete Procedure API methods can execute if trustedAuthorization is set to False on the AgilePoint Server.
        Limitations:
        This access right only applies in these conditions:
        • AgilePoint NX OnPremises or AgilePoint NX PrivateCloud.
        • In the AgilePoint Server netflow.cfg file, trustedAuthorization is set to False.

          By default, trustedAuthorization is set to True. As such, this access control only applies if this configuration setting is changed on the AgilePoint Server.

        • A system activity or custom AgilePart runs.

          More specifically, this access control tends to affect asynchronous type system activities, which must wait for input from an external system, such as a database or cloud-based service. If both trustedAuthorization and the Mark Automatic Work Item Completion access control are turned off (deselected or set to False), and the Complete Automatic Work Item method is called (usually from an API application), asynchronous activities may throw an Access Denied exception.

        • System activities do not require intervention from human users. Therefore, this access control usually applies to either a user account associated with an API method call, or the AgilePoint Service Account. The Service Account is sometimes also used for API applications.
        Allowed Values:
        • Selected - If trustedAuthorization is set to False, the Complete Automatic Work Item API method can execute.

          This setting has no effect in these cases:

        • Deselected - If trustedAuthorization is set to False, access to the Complete Automatic Work Item API method is denied.

          For more information, refer to Why Do I Get an Access Denied Error for an API Method Call?

        Default Value:
        Deselected
    • To enable the Query Database and Query Database (Extended) methods:
      1. Click the Process tab.
      2. Select Allow to Execute QueryDatabase() and QueryDatabaseEx().
        Field NameDefinition

        Allow To Execute QueryDatabase() And QueryDatabaseEx()
        Description:
        Specifies whether the Query Database and Query Database (Extended Method) API methods can execute if trustedAuthorization is set to False on the AgilePoint Server.
        Limitations:
        This access right only applies in these conditions:
        Allowed Values:
        • Selected - If trustedAuthorization is set to False, the Query Database and Query Database (Extended Method) API method can execute.
        • Deselected - If trustedAuthorization is set to False, access to the Query Database and Query Database (Extended Method) API method is denied.

          For more information, refer to Why Do I Get an Access Denied Error for an API Method Call?

        Default Value:
        Deselected
    • To enable the Save Temporary File method:
      1. Click the Applicaiton Builder tab.
      2. Select Save, Remove Temporary File.
        Field NameDefinition

        Save And Remove Temporary Files (API)
        Description:
        Specifies whether the Save Temporary File and Remove Temporary File API methods can execute if trustedAuthorization is set to False on the AgilePoint Server.
        Limitations:
        This access right only applies in these conditions:
        Allowed Values:
        • Selected - If trustedAuthorization is set to False, the Save Temporary File and Remove Temporary File API method can execute.

          This setting has no effect in these cases:

          • trustedAuthorization is set to True
        • Deselected - If trustedAuthorization is set to False, access to the Save Temporary File and Remove Temporary File API method is denied.

          For more information, refer to Why Do I Get an Access Denied Error for an API Method Call?

        Default Value:
        Deselected